@ttoss/fsl-ui 0.2.4

package/dist/semantics/taxonomy.cjs

@@ -0,0 +1,150 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+//#region src/semantics/taxonomy.ts
+/**
+* Layer 1 — Semantic Foundation: Vocabulary
+*
+* Values-first: constants are the source of truth.
+* Types are derived from constants via `typeof … [number]`.
+*
+* No imports — this module is the dependency root of the entire system.
+*
+* @see FSL Lexicon §1–7
+* @see ../tokens/CONTRACT.md — AI-facing guide that consumes this vocabulary
+*   to tell component authors which `vars.*` paths to use per Entity.
+*/
+var ENTITIES = ["Action", "Input", "Selection", "Collection", "Overlay", "Navigation", "Disclosure", "Feedback", "Structure"];
+var STRUCTURAL_ROLES = ["root", "control", "surface", "content", "label", "description", "title", "body", "actions", "status", "icon", "indicator", "item", "trigger", "backdrop", "positioner", "closeTrigger", "selectionControl", "leadingAdornment", "trailingAdornment", "validationMessage"];
+var EVALUATIONS = ["primary", "secondary", "accent", "muted", "positive", "caution", "negative"];
+var COMPOSITION_ROLES = ["primaryAction", "secondaryAction", "dismissAction", "heading", "body", "status", "control", "label", "description", "supporting", "selection", "step", "summary", "navigation"];
+var CONSEQUENCES = ["neutral", "committing", "destructive"];
+var STATES = ["default", "hover", "active", "focused", "disabled", "selected", "pressed", "checked", "indeterminate", "expanded", "current", "visited", "droptarget", "invalid"];
+var STATE_PRIORITY = [{
+  flag: "isDisabled",
+  state: "disabled"
+}, {
+  flag: "isInvalid",
+  state: "invalid"
+}, {
+  flag: "isExpanded",
+  state: "expanded"
+}, {
+  flag: "isIndeterminate",
+  state: "indeterminate"
+}, {
+  flag: "isSelected",
+  state: "checked"
+}, {
+  flag: "isFocusVisible",
+  state: "focused"
+}, {
+  flag: "isPressed",
+  state: "active"
+}, {
+  flag: "isHovered",
+  state: "hover"
+}];
+/** Which structural roles are legal for each entity. */
+var ENTITY_STRUCTURE = {
+  Action: ["root", "control", "icon", "label"],
+  Input: ["root", "control", "label", "description", "leadingAdornment", "trailingAdornment", "validationMessage"],
+  Selection: ["root", "control", "label", "indicator", "selectionControl", "item"],
+  Collection: ["root", "surface", "content", "item", "title", "actions"],
+  Overlay: ["root", "surface", "content", "title", "body", "actions", "backdrop", "positioner", "closeTrigger"],
+  Navigation: ["root", "control", "label", "icon", "indicator", "item"],
+  Disclosure: ["root", "trigger", "content", "icon", "indicator"],
+  Feedback: ["root", "content", "icon", "title", "body", "actions", "status", "closeTrigger"],
+  Structure: ["root", "surface", "content", "title", "body", "label", "description", "icon", "actions"]
+};
+/**
+* Which evaluations are legal for each entity.
+*
+* Design note — `Input` and `Selection` carry **no** evaluations. Form
+* controls are data-entry surfaces, not decision hierarchies: there is no
+* authorial choice between `primary`/`secondary`/`muted` for a text field or
+* a checkbox, and validation outcome is not authorial either — it is a
+* runtime fact emitted by a form library or a `validate()` callback.
+*
+* The vocabulary distinction:
+*   - `Evaluation` (this matrix) is **authorial emphasis/valence**.
+*   - `State.invalid` (see `STATES`) is the **runtime validation outcome**.
+*
+* This mirrors the Lexicon §10.5 distinction `negative ≠ destructive`:
+* evaluation lives in the author's pen, state lives in the user's data. By
+* keeping the two separate the system avoids the shape where a developer is
+* tempted to write `<TextField evaluation="negative">` to express a
+* validation error — that is a category mistake. The correct expression is
+* `<TextField isInvalid />`, which flips the `invalid` state and lets the
+* single neutral chrome become the canonical validation surface.
+*
+* Adjacent slots (description, icon, validationMessage) may still consume
+* `vars.colors.input.{positive|caution|negative}` directly when they need
+* valence — those are *display* of validation context, not the control
+* itself.
+*
+* Consensus pattern across React Aria (`isInvalid`), Adobe Spectrum
+* (`validationState`), Material UI (`error`), Ant Design (`status`), and
+* shadcn/ui (`aria-invalid`): validation is exposed as boolean state on the
+* control, not as a coloring variant.
+*/
+var ENTITY_EVALUATION = {
+  Action: ["primary", "secondary", "accent", "muted", "negative"],
+  Input: [],
+  Selection: [],
+  Collection: ["primary", "muted"],
+  Overlay: ["primary", "secondary", "accent", "muted", "negative"],
+  Navigation: ["primary", "secondary", "accent", "muted"],
+  Disclosure: ["primary", "muted"],
+  Feedback: ["primary", "positive", "caution", "negative"],
+  Structure: ["primary", "muted"]
+};
+/**
+* Which composition roles an entity of this kind may play inside a parent
+* composite. `[]` means the entity is a host or leaf: it does not participate
+* in a larger composition as a slot-bearing child.
+*
+* Readmit roles per-entity only when a concrete component exercises the slot.
+*/
+var ENTITY_COMPOSITION = {
+  Action: ["primaryAction", "secondaryAction", "dismissAction"],
+  Input: ["control", "label", "description", "status", "supporting"],
+  Selection: ["control", "selection", "label", "description"],
+  Collection: [],
+  Overlay: ["heading", "body"],
+  Navigation: [],
+  Disclosure: [],
+  Feedback: ["status"],
+  Structure: ["heading", "body", "label", "description", "supporting", "step", "summary", "navigation"]
+};
+/**
+* Which consequence values are legal for each entity.
+*
+* `Action` is the only entity whose interactions produce authorial effect-
+* on-state today (`committing` submits, `destructive` deletes, `neutral`
+* everything else). Other entities' interactions — input entry, navigation
+* — do not carry the same authorial "what does this do" meta and are
+* intentionally left empty.
+*/
+var ENTITY_CONSEQUENCE = {
+  Action: ["neutral", "committing", "destructive"],
+  Input: [],
+  Selection: [],
+  Collection: [],
+  Overlay: [],
+  Navigation: [],
+  Disclosure: [],
+  Feedback: [],
+  Structure: []
+};
+
+//#endregion
+exports.COMPOSITION_ROLES = COMPOSITION_ROLES;
+exports.CONSEQUENCES = CONSEQUENCES;
+exports.ENTITIES = ENTITIES;
+exports.ENTITY_COMPOSITION = ENTITY_COMPOSITION;
+exports.ENTITY_CONSEQUENCE = ENTITY_CONSEQUENCE;
+exports.ENTITY_EVALUATION = ENTITY_EVALUATION;
+exports.ENTITY_STRUCTURE = ENTITY_STRUCTURE;
+exports.EVALUATIONS = EVALUATIONS;
+exports.STATES = STATES;
+exports.STATE_PRIORITY = STATE_PRIORITY;
+exports.STRUCTURAL_ROLES = STRUCTURAL_ROLES;

package/dist/semantics/taxonomy.d.cts

@@ -0,0 +1,153 @@
+
+//#region src/semantics/taxonomy.d.ts
+/**
+ * Layer 1 — Semantic Foundation: Vocabulary
+ *
+ * Values-first: constants are the source of truth.
+ * Types are derived from constants via `typeof … [number]`.
+ *
+ * No imports — this module is the dependency root of the entire system.
+ *
+ * @see FSL Lexicon §1–7
+ * @see ../tokens/CONTRACT.md — AI-facing guide that consumes this vocabulary
+ *   to tell component authors which `vars.*` paths to use per Entity.
+ */
+declare const ENTITIES: readonly ["Action", "Input", "Selection", "Collection", "Overlay", "Navigation", "Disclosure", "Feedback", "Structure"];
+type Entity = (typeof ENTITIES)[number];
+declare const STRUCTURAL_ROLES: readonly ["root", "control", "surface", "content", "label", "description", "title", "body", "actions", "status", "icon", "indicator", "item", "trigger", "backdrop", "positioner", "closeTrigger", "selectionControl", "leadingAdornment", "trailingAdornment", "validationMessage"];
+type StructuralRole = (typeof STRUCTURAL_ROLES)[number];
+declare const EVALUATIONS: readonly ["primary", "secondary", "accent", "muted", "positive", "caution", "negative"];
+type Evaluation = (typeof EVALUATIONS)[number];
+declare const COMPOSITION_ROLES: readonly ["primaryAction", "secondaryAction", "dismissAction", "heading", "body", "status", "control", "label", "description", "supporting", "selection", "step", "summary", "navigation"];
+type CompositionRole = (typeof COMPOSITION_ROLES)[number];
+declare const CONSEQUENCES: readonly ["neutral", "committing", "destructive"];
+type Consequence = (typeof CONSEQUENCES)[number];
+declare const STATES: readonly ["default", "hover", "active", "focused", "disabled", "selected", "pressed", "checked", "indeterminate", "expanded", "current", "visited", "droptarget", "invalid"];
+type State = (typeof STATES)[number];
+declare const STATE_PRIORITY: readonly [{
+  readonly flag: "isDisabled";
+  readonly state: "disabled";
+}, {
+  readonly flag: "isInvalid";
+  readonly state: "invalid";
+}, {
+  readonly flag: "isExpanded";
+  readonly state: "expanded";
+}, {
+  readonly flag: "isIndeterminate";
+  readonly state: "indeterminate";
+}, {
+  readonly flag: "isSelected";
+  readonly state: "checked";
+}, {
+  readonly flag: "isFocusVisible";
+  readonly state: "focused";
+}, {
+  readonly flag: "isPressed";
+  readonly state: "active";
+}, {
+  readonly flag: "isHovered";
+  readonly state: "hover";
+}];
+/** Which structural roles are legal for each entity. */
+declare const ENTITY_STRUCTURE: {
+  readonly Action: readonly ["root", "control", "icon", "label"];
+  readonly Input: readonly ["root", "control", "label", "description", "leadingAdornment", "trailingAdornment", "validationMessage"];
+  readonly Selection: readonly ["root", "control", "label", "indicator", "selectionControl", "item"];
+  readonly Collection: readonly ["root", "surface", "content", "item", "title", "actions"];
+  readonly Overlay: readonly ["root", "surface", "content", "title", "body", "actions", "backdrop", "positioner", "closeTrigger"];
+  readonly Navigation: readonly ["root", "control", "label", "icon", "indicator", "item"];
+  readonly Disclosure: readonly ["root", "trigger", "content", "icon", "indicator"];
+  readonly Feedback: readonly ["root", "content", "icon", "title", "body", "actions", "status", "closeTrigger"];
+  readonly Structure: readonly ["root", "surface", "content", "title", "body", "label", "description", "icon", "actions"];
+};
+/**
+ * Which evaluations are legal for each entity.
+ *
+ * Design note — `Input` and `Selection` carry **no** evaluations. Form
+ * controls are data-entry surfaces, not decision hierarchies: there is no
+ * authorial choice between `primary`/`secondary`/`muted` for a text field or
+ * a checkbox, and validation outcome is not authorial either — it is a
+ * runtime fact emitted by a form library or a `validate()` callback.
+ *
+ * The vocabulary distinction:
+ *   - `Evaluation` (this matrix) is **authorial emphasis/valence**.
+ *   - `State.invalid` (see `STATES`) is the **runtime validation outcome**.
+ *
+ * This mirrors the Lexicon §10.5 distinction `negative ≠ destructive`:
+ * evaluation lives in the author's pen, state lives in the user's data. By
+ * keeping the two separate the system avoids the shape where a developer is
+ * tempted to write `<TextField evaluation="negative">` to express a
+ * validation error — that is a category mistake. The correct expression is
+ * `<TextField isInvalid />`, which flips the `invalid` state and lets the
+ * single neutral chrome become the canonical validation surface.
+ *
+ * Adjacent slots (description, icon, validationMessage) may still consume
+ * `vars.colors.input.{positive|caution|negative}` directly when they need
+ * valence — those are *display* of validation context, not the control
+ * itself.
+ *
+ * Consensus pattern across React Aria (`isInvalid`), Adobe Spectrum
+ * (`validationState`), Material UI (`error`), Ant Design (`status`), and
+ * shadcn/ui (`aria-invalid`): validation is exposed as boolean state on the
+ * control, not as a coloring variant.
+ */
+declare const ENTITY_EVALUATION: {
+  readonly Action: readonly ["primary", "secondary", "accent", "muted", "negative"];
+  readonly Input: readonly [];
+  readonly Selection: readonly [];
+  readonly Collection: readonly ["primary", "muted"];
+  readonly Overlay: readonly ["primary", "secondary", "accent", "muted", "negative"];
+  readonly Navigation: readonly ["primary", "secondary", "accent", "muted"];
+  readonly Disclosure: readonly ["primary", "muted"];
+  readonly Feedback: readonly ["primary", "positive", "caution", "negative"];
+  readonly Structure: readonly ["primary", "muted"];
+};
+/**
+ * Which composition roles an entity of this kind may play inside a parent
+ * composite. `[]` means the entity is a host or leaf: it does not participate
+ * in a larger composition as a slot-bearing child.
+ *
+ * Readmit roles per-entity only when a concrete component exercises the slot.
+ */
+declare const ENTITY_COMPOSITION: {
+  readonly Action: readonly ["primaryAction", "secondaryAction", "dismissAction"];
+  readonly Input: readonly ["control", "label", "description", "status", "supporting"];
+  readonly Selection: readonly ["control", "selection", "label", "description"];
+  readonly Collection: readonly [];
+  readonly Overlay: readonly ["heading", "body"];
+  readonly Navigation: readonly [];
+  readonly Disclosure: readonly [];
+  readonly Feedback: readonly ["status"];
+  readonly Structure: readonly ["heading", "body", "label", "description", "supporting", "step", "summary", "navigation"];
+};
+/**
+ * Which consequence values are legal for each entity.
+ *
+ * `Action` is the only entity whose interactions produce authorial effect-
+ * on-state today (`committing` submits, `destructive` deletes, `neutral`
+ * everything else). Other entities' interactions — input entry, navigation
+ * — do not carry the same authorial "what does this do" meta and are
+ * intentionally left empty.
+ */
+declare const ENTITY_CONSEQUENCE: {
+  readonly Action: readonly ["neutral", "committing", "destructive"];
+  readonly Input: readonly [];
+  readonly Selection: readonly [];
+  readonly Collection: readonly [];
+  readonly Overlay: readonly [];
+  readonly Navigation: readonly [];
+  readonly Disclosure: readonly [];
+  readonly Feedback: readonly [];
+  readonly Structure: readonly [];
+};
+/** Structural roles that are legal for entity E. */
+type StructuresFor<E extends Entity> = (typeof ENTITY_STRUCTURE)[E][number];
+/** Evaluations that are legal for entity E. */
+type EvaluationsFor<E extends Entity> = (typeof ENTITY_EVALUATION)[E][number];
+/** Composition roles that are legal for entity E. */
+type CompositionsFor<E extends Entity> = (typeof ENTITY_COMPOSITION)[E][number];
+/** Consequence values that are legal for entity E. */
+type ConsequencesFor<E extends Entity> = (typeof ENTITY_CONSEQUENCE)[E][number];
+//#endregion
+export { COMPOSITION_ROLES, CONSEQUENCES, CompositionRole, CompositionsFor, Consequence, ConsequencesFor, ENTITIES, ENTITY_COMPOSITION, ENTITY_CONSEQUENCE, ENTITY_EVALUATION, ENTITY_STRUCTURE, EVALUATIONS, Entity, Evaluation, EvaluationsFor, STATES, STATE_PRIORITY, STRUCTURAL_ROLES, State, StructuralRole, StructuresFor };

package/dist/semantics/taxonomy.d.mts

@@ -0,0 +1,153 @@
+
+//#region src/semantics/taxonomy.d.ts
+/**
+ * Layer 1 — Semantic Foundation: Vocabulary
+ *
+ * Values-first: constants are the source of truth.
+ * Types are derived from constants via `typeof … [number]`.
+ *
+ * No imports — this module is the dependency root of the entire system.
+ *
+ * @see FSL Lexicon §1–7
+ * @see ../tokens/CONTRACT.md — AI-facing guide that consumes this vocabulary
+ *   to tell component authors which `vars.*` paths to use per Entity.
+ */
+declare const ENTITIES: readonly ["Action", "Input", "Selection", "Collection", "Overlay", "Navigation", "Disclosure", "Feedback", "Structure"];
+type Entity = (typeof ENTITIES)[number];
+declare const STRUCTURAL_ROLES: readonly ["root", "control", "surface", "content", "label", "description", "title", "body", "actions", "status", "icon", "indicator", "item", "trigger", "backdrop", "positioner", "closeTrigger", "selectionControl", "leadingAdornment", "trailingAdornment", "validationMessage"];
+type StructuralRole = (typeof STRUCTURAL_ROLES)[number];
+declare const EVALUATIONS: readonly ["primary", "secondary", "accent", "muted", "positive", "caution", "negative"];
+type Evaluation = (typeof EVALUATIONS)[number];
+declare const COMPOSITION_ROLES: readonly ["primaryAction", "secondaryAction", "dismissAction", "heading", "body", "status", "control", "label", "description", "supporting", "selection", "step", "summary", "navigation"];
+type CompositionRole = (typeof COMPOSITION_ROLES)[number];
+declare const CONSEQUENCES: readonly ["neutral", "committing", "destructive"];
+type Consequence = (typeof CONSEQUENCES)[number];
+declare const STATES: readonly ["default", "hover", "active", "focused", "disabled", "selected", "pressed", "checked", "indeterminate", "expanded", "current", "visited", "droptarget", "invalid"];
+type State = (typeof STATES)[number];
+declare const STATE_PRIORITY: readonly [{
+  readonly flag: "isDisabled";
+  readonly state: "disabled";
+}, {
+  readonly flag: "isInvalid";
+  readonly state: "invalid";
+}, {
+  readonly flag: "isExpanded";
+  readonly state: "expanded";
+}, {
+  readonly flag: "isIndeterminate";
+  readonly state: "indeterminate";
+}, {
+  readonly flag: "isSelected";
+  readonly state: "checked";
+}, {
+  readonly flag: "isFocusVisible";
+  readonly state: "focused";
+}, {
+  readonly flag: "isPressed";
+  readonly state: "active";
+}, {
+  readonly flag: "isHovered";
+  readonly state: "hover";
+}];
+/** Which structural roles are legal for each entity. */
+declare const ENTITY_STRUCTURE: {
+  readonly Action: readonly ["root", "control", "icon", "label"];
+  readonly Input: readonly ["root", "control", "label", "description", "leadingAdornment", "trailingAdornment", "validationMessage"];
+  readonly Selection: readonly ["root", "control", "label", "indicator", "selectionControl", "item"];
+  readonly Collection: readonly ["root", "surface", "content", "item", "title", "actions"];
+  readonly Overlay: readonly ["root", "surface", "content", "title", "body", "actions", "backdrop", "positioner", "closeTrigger"];
+  readonly Navigation: readonly ["root", "control", "label", "icon", "indicator", "item"];
+  readonly Disclosure: readonly ["root", "trigger", "content", "icon", "indicator"];
+  readonly Feedback: readonly ["root", "content", "icon", "title", "body", "actions", "status", "closeTrigger"];
+  readonly Structure: readonly ["root", "surface", "content", "title", "body", "label", "description", "icon", "actions"];
+};
+/**
+ * Which evaluations are legal for each entity.
+ *
+ * Design note — `Input` and `Selection` carry **no** evaluations. Form
+ * controls are data-entry surfaces, not decision hierarchies: there is no
+ * authorial choice between `primary`/`secondary`/`muted` for a text field or
+ * a checkbox, and validation outcome is not authorial either — it is a
+ * runtime fact emitted by a form library or a `validate()` callback.
+ *
+ * The vocabulary distinction:
+ *   - `Evaluation` (this matrix) is **authorial emphasis/valence**.
+ *   - `State.invalid` (see `STATES`) is the **runtime validation outcome**.
+ *
+ * This mirrors the Lexicon §10.5 distinction `negative ≠ destructive`:
+ * evaluation lives in the author's pen, state lives in the user's data. By
+ * keeping the two separate the system avoids the shape where a developer is
+ * tempted to write `<TextField evaluation="negative">` to express a
+ * validation error — that is a category mistake. The correct expression is
+ * `<TextField isInvalid />`, which flips the `invalid` state and lets the
+ * single neutral chrome become the canonical validation surface.
+ *
+ * Adjacent slots (description, icon, validationMessage) may still consume
+ * `vars.colors.input.{positive|caution|negative}` directly when they need
+ * valence — those are *display* of validation context, not the control
+ * itself.
+ *
+ * Consensus pattern across React Aria (`isInvalid`), Adobe Spectrum
+ * (`validationState`), Material UI (`error`), Ant Design (`status`), and
+ * shadcn/ui (`aria-invalid`): validation is exposed as boolean state on the
+ * control, not as a coloring variant.
+ */
+declare const ENTITY_EVALUATION: {
+  readonly Action: readonly ["primary", "secondary", "accent", "muted", "negative"];
+  readonly Input: readonly [];
+  readonly Selection: readonly [];
+  readonly Collection: readonly ["primary", "muted"];
+  readonly Overlay: readonly ["primary", "secondary", "accent", "muted", "negative"];
+  readonly Navigation: readonly ["primary", "secondary", "accent", "muted"];
+  readonly Disclosure: readonly ["primary", "muted"];
+  readonly Feedback: readonly ["primary", "positive", "caution", "negative"];
+  readonly Structure: readonly ["primary", "muted"];
+};
+/**
+ * Which composition roles an entity of this kind may play inside a parent
+ * composite. `[]` means the entity is a host or leaf: it does not participate
+ * in a larger composition as a slot-bearing child.
+ *
+ * Readmit roles per-entity only when a concrete component exercises the slot.
+ */
+declare const ENTITY_COMPOSITION: {
+  readonly Action: readonly ["primaryAction", "secondaryAction", "dismissAction"];
+  readonly Input: readonly ["control", "label", "description", "status", "supporting"];
+  readonly Selection: readonly ["control", "selection", "label", "description"];
+  readonly Collection: readonly [];
+  readonly Overlay: readonly ["heading", "body"];
+  readonly Navigation: readonly [];
+  readonly Disclosure: readonly [];
+  readonly Feedback: readonly ["status"];
+  readonly Structure: readonly ["heading", "body", "label", "description", "supporting", "step", "summary", "navigation"];
+};
+/**
+ * Which consequence values are legal for each entity.
+ *
+ * `Action` is the only entity whose interactions produce authorial effect-
+ * on-state today (`committing` submits, `destructive` deletes, `neutral`
+ * everything else). Other entities' interactions — input entry, navigation
+ * — do not carry the same authorial "what does this do" meta and are
+ * intentionally left empty.
+ */
+declare const ENTITY_CONSEQUENCE: {
+  readonly Action: readonly ["neutral", "committing", "destructive"];
+  readonly Input: readonly [];
+  readonly Selection: readonly [];
+  readonly Collection: readonly [];
+  readonly Overlay: readonly [];
+  readonly Navigation: readonly [];
+  readonly Disclosure: readonly [];
+  readonly Feedback: readonly [];
+  readonly Structure: readonly [];
+};
+/** Structural roles that are legal for entity E. */
+type StructuresFor<E extends Entity> = (typeof ENTITY_STRUCTURE)[E][number];
+/** Evaluations that are legal for entity E. */
+type EvaluationsFor<E extends Entity> = (typeof ENTITY_EVALUATION)[E][number];
+/** Composition roles that are legal for entity E. */
+type CompositionsFor<E extends Entity> = (typeof ENTITY_COMPOSITION)[E][number];
+/** Consequence values that are legal for entity E. */
+type ConsequencesFor<E extends Entity> = (typeof ENTITY_CONSEQUENCE)[E][number];
+//#endregion
+export { COMPOSITION_ROLES, CONSEQUENCES, CompositionRole, CompositionsFor, Consequence, ConsequencesFor, ENTITIES, ENTITY_COMPOSITION, ENTITY_CONSEQUENCE, ENTITY_EVALUATION, ENTITY_STRUCTURE, EVALUATIONS, Entity, Evaluation, EvaluationsFor, STATES, STATE_PRIORITY, STRUCTURAL_ROLES, State, StructuralRole, StructuresFor };

package/dist/semantics/taxonomy.mjs

@@ -0,0 +1,140 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+//#region src/semantics/taxonomy.ts
+/**
+* Layer 1 — Semantic Foundation: Vocabulary
+*
+* Values-first: constants are the source of truth.
+* Types are derived from constants via `typeof … [number]`.
+*
+* No imports — this module is the dependency root of the entire system.
+*
+* @see FSL Lexicon §1–7
+* @see ../tokens/CONTRACT.md — AI-facing guide that consumes this vocabulary
+*   to tell component authors which `vars.*` paths to use per Entity.
+*/
+var ENTITIES = ["Action", "Input", "Selection", "Collection", "Overlay", "Navigation", "Disclosure", "Feedback", "Structure"];
+var STRUCTURAL_ROLES = ["root", "control", "surface", "content", "label", "description", "title", "body", "actions", "status", "icon", "indicator", "item", "trigger", "backdrop", "positioner", "closeTrigger", "selectionControl", "leadingAdornment", "trailingAdornment", "validationMessage"];
+var EVALUATIONS = ["primary", "secondary", "accent", "muted", "positive", "caution", "negative"];
+var COMPOSITION_ROLES = ["primaryAction", "secondaryAction", "dismissAction", "heading", "body", "status", "control", "label", "description", "supporting", "selection", "step", "summary", "navigation"];
+var CONSEQUENCES = ["neutral", "committing", "destructive"];
+var STATES = ["default", "hover", "active", "focused", "disabled", "selected", "pressed", "checked", "indeterminate", "expanded", "current", "visited", "droptarget", "invalid"];
+var STATE_PRIORITY = [{
+  flag: "isDisabled",
+  state: "disabled"
+}, {
+  flag: "isInvalid",
+  state: "invalid"
+}, {
+  flag: "isExpanded",
+  state: "expanded"
+}, {
+  flag: "isIndeterminate",
+  state: "indeterminate"
+}, {
+  flag: "isSelected",
+  state: "checked"
+}, {
+  flag: "isFocusVisible",
+  state: "focused"
+}, {
+  flag: "isPressed",
+  state: "active"
+}, {
+  flag: "isHovered",
+  state: "hover"
+}];
+/** Which structural roles are legal for each entity. */
+var ENTITY_STRUCTURE = {
+  Action: ["root", "control", "icon", "label"],
+  Input: ["root", "control", "label", "description", "leadingAdornment", "trailingAdornment", "validationMessage"],
+  Selection: ["root", "control", "label", "indicator", "selectionControl", "item"],
+  Collection: ["root", "surface", "content", "item", "title", "actions"],
+  Overlay: ["root", "surface", "content", "title", "body", "actions", "backdrop", "positioner", "closeTrigger"],
+  Navigation: ["root", "control", "label", "icon", "indicator", "item"],
+  Disclosure: ["root", "trigger", "content", "icon", "indicator"],
+  Feedback: ["root", "content", "icon", "title", "body", "actions", "status", "closeTrigger"],
+  Structure: ["root", "surface", "content", "title", "body", "label", "description", "icon", "actions"]
+};
+/**
+* Which evaluations are legal for each entity.
+*
+* Design note — `Input` and `Selection` carry **no** evaluations. Form
+* controls are data-entry surfaces, not decision hierarchies: there is no
+* authorial choice between `primary`/`secondary`/`muted` for a text field or
+* a checkbox, and validation outcome is not authorial either — it is a
+* runtime fact emitted by a form library or a `validate()` callback.
+*
+* The vocabulary distinction:
+*   - `Evaluation` (this matrix) is **authorial emphasis/valence**.
+*   - `State.invalid` (see `STATES`) is the **runtime validation outcome**.
+*
+* This mirrors the Lexicon §10.5 distinction `negative ≠ destructive`:
+* evaluation lives in the author's pen, state lives in the user's data. By
+* keeping the two separate the system avoids the shape where a developer is
+* tempted to write `<TextField evaluation="negative">` to express a
+* validation error — that is a category mistake. The correct expression is
+* `<TextField isInvalid />`, which flips the `invalid` state and lets the
+* single neutral chrome become the canonical validation surface.
+*
+* Adjacent slots (description, icon, validationMessage) may still consume
+* `vars.colors.input.{positive|caution|negative}` directly when they need
+* valence — those are *display* of validation context, not the control
+* itself.
+*
+* Consensus pattern across React Aria (`isInvalid`), Adobe Spectrum
+* (`validationState`), Material UI (`error`), Ant Design (`status`), and
+* shadcn/ui (`aria-invalid`): validation is exposed as boolean state on the
+* control, not as a coloring variant.
+*/
+var ENTITY_EVALUATION = {
+  Action: ["primary", "secondary", "accent", "muted", "negative"],
+  Input: [],
+  Selection: [],
+  Collection: ["primary", "muted"],
+  Overlay: ["primary", "secondary", "accent", "muted", "negative"],
+  Navigation: ["primary", "secondary", "accent", "muted"],
+  Disclosure: ["primary", "muted"],
+  Feedback: ["primary", "positive", "caution", "negative"],
+  Structure: ["primary", "muted"]
+};
+/**
+* Which composition roles an entity of this kind may play inside a parent
+* composite. `[]` means the entity is a host or leaf: it does not participate
+* in a larger composition as a slot-bearing child.
+*
+* Readmit roles per-entity only when a concrete component exercises the slot.
+*/
+var ENTITY_COMPOSITION = {
+  Action: ["primaryAction", "secondaryAction", "dismissAction"],
+  Input: ["control", "label", "description", "status", "supporting"],
+  Selection: ["control", "selection", "label", "description"],
+  Collection: [],
+  Overlay: ["heading", "body"],
+  Navigation: [],
+  Disclosure: [],
+  Feedback: ["status"],
+  Structure: ["heading", "body", "label", "description", "supporting", "step", "summary", "navigation"]
+};
+/**
+* Which consequence values are legal for each entity.
+*
+* `Action` is the only entity whose interactions produce authorial effect-
+* on-state today (`committing` submits, `destructive` deletes, `neutral`
+* everything else). Other entities' interactions — input entry, navigation
+* — do not carry the same authorial "what does this do" meta and are
+* intentionally left empty.
+*/
+var ENTITY_CONSEQUENCE = {
+  Action: ["neutral", "committing", "destructive"],
+  Input: [],
+  Selection: [],
+  Collection: [],
+  Overlay: [],
+  Navigation: [],
+  Disclosure: [],
+  Feedback: [],
+  Structure: []
+};
+
+//#endregion
+export { COMPOSITION_ROLES, CONSEQUENCES, ENTITIES, ENTITY_COMPOSITION, ENTITY_CONSEQUENCE, ENTITY_EVALUATION, ENTITY_STRUCTURE, EVALUATIONS, STATES, STATE_PRIORITY, STRUCTURAL_ROLES };

package/dist/tokens/escapeHatch.cjs

@@ -0,0 +1,13 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+//#region src/tokens/escapeHatch.ts
+/**
+* Composes a `var()` read of a host knob with its required fallback.
+* The fallback is the component's default — a knob without a fallback is a
+* contract violation (enforced by the contract test suite).
+*/
+var fslVar = (knob, fallback) => {
+  return `var(${knob}, ${fallback})`;
+};
+
+//#endregion
+exports.fslVar = fslVar;

package/dist/tokens/escapeHatch.mjs

@@ -0,0 +1,13 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+//#region src/tokens/escapeHatch.ts
+/**
+* Composes a `var()` read of a host knob with its required fallback.
+* The fallback is the component's default — a knob without a fallback is a
+* contract violation (enforced by the contract test suite).
+*/
+var fslVar = (knob, fallback) => {
+  return `var(${knob}, ${fallback})`;
+};
+
+//#endregion
+export { fslVar };

package/dist/tokens/focusRing.cjs

@@ -0,0 +1,28 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+let _ttoss_fsl_theme_vars = require("@ttoss/fsl-theme/vars");
+
+//#region src/tokens/focusRing.ts
+/**
+* Focus ring resolver — the cross-cutting keyboard-focus outline every
+* interactive component applies per `CONTRACT.md §3`:
+*
+*   - always via `outline` (never `border`) so focus cannot layout-shift;
+*   - always from the cross-cutting `vars.focus.ring.*` tokens (CONTRACT §1
+*     cross-cutting table), never from per-entity color subtrees.
+*
+* Companion to `resolveInteractiveStyle`: that helper owns the state
+* cascade for color dimensions; this one owns the single state-dependent
+* outline. Both exist so components never re-implement state ternaries
+* (structural tokens like radii/spacing stay literal reads by design).
+*/
+/**
+* Returns the `outline` CSS value for the current focus-visible state.
+* Pair with `outlineOffset` at the call site when the component floats the
+* ring off its edge.
+*/
+var focusRingOutline = isFocusVisible => {
+  return isFocusVisible ? `${_ttoss_fsl_theme_vars.vars.focus.ring.width} ${_ttoss_fsl_theme_vars.vars.focus.ring.style} ${_ttoss_fsl_theme_vars.vars.focus.ring.color}` : "none";
+};
+
+//#endregion
+exports.focusRingOutline = focusRingOutline;