Skip to content

docs(adr): add ADR 0008 for typed API ergonomics and safety hardening - #399

Merged
tiensonqin merged 1 commit into
mainfrom
logseq/adr-0008-typed-api-followup-3f2a
Nov 20, 2026
Merged

tiensonqin merged 1 commit into
mainfrom
logseq/adr-0008-typed-api-followup-3f2a

Conversation

@tiensonqin

@tiensonqin tiensonqin commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Adds ADR 0008 (docs/adr/0008-typed-api-ergonomics-and-safety-hardening.md), documenting the post-ADR 0007 audit findings and follow-up design for LUI's typed component API before downstream apps standardize on it.

Key topics covered

  • P1 — Compile-time safety, PPX façade parity, and reactive diffing:
    • Capability-indexed -'caps Slot_style.t to eliminate runtime Invalid_argument exceptions on unsupported (kind, property) pairs and remove the style exemption in tooling/test/component_schema_test.mjs.
    • Full Lui.Elements / Lui.Ui / Lui.Raw / Lui.Elements.Slot_style.make resolution in ppx/lui_ppx.ml and ppx/lui_nesting.ml.
    • Diff-aware apply_popover_target (avoiding redundant 8-key RemoveProp churn) and single-emit split initialization when sizing_signal is provided.
    • Segment-scoped rollback, unchanged-order fast path, direct positional insertion, and O(n log n) minimal-move reconciliation in keyed_range.
  • P2 — Ergonomics, polymorphic phantom elements, and Tier-1 / token completeness:
    • Unifying the 14 monomorphic slot types onto polymorphic 'kind el with uniform if_ / keyed / scoped / reactive combinators and schema-generated src/lui_elements.mli.
    • Removing include Lui_ui from src/lui_ui_composites.ml, adding src/lui_ui_composites.mli, fixing static/reactive parameter symmetry (Ui.form_sheet, Ui.form_field), and making Ui.form_section / Ui.data_list dynamic-child safe.
    • Full Lui.Tokens adoption with platform-adaptive spacing metrics across Web, Apple, Android, and Native.
  • P3 — Precedence and wire consistency:
    • Applying Slot_style before apply_text_recipe so ~truncate:true is preserved.
    • Aligning ?style on menu / submenu / popover and migrating dropdown_menu to popover_target.
    • Completing numeric clamping in Lui_protocol.normalize_property_value and unifying Lui_json_view enum error handling.

Testing

  • Documentation-only PR (docs/adr/0008-typed-api-ergonomics-and-safety-hardening.md).
  • Verified baseline repo build & test suite (opam exec -- dune build @all @web, make test-schema, make test-ocaml, npm --prefix platform/web run check) prior to branching.
Open in Web Open in Cursor 

Devin Review

Co-authored-by: Tienson Qin <tiensonqin@gmail.com>

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

Devin Review

@tiensonqin
tiensonqin merged commit f28762c into main Nov 20, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants