@ecoma-io/loom 0.1.1 → 0.2.0

package/dist/lib/field-context.d.ts

@@ -0,0 +1,178 @@
+import { type ComputedRef } from "vue";
+/**
+ * What a form-row wrapper (Field, Fieldset) knows about the control inside it.
+ *
+ * A wrapper renders a `<label for>` and a hint-or-error line, and it is the
+ * only thing in the tree that knows the id it pointed that label at, the id of
+ * the message, and whether the row is mandatory or in error. None of that can
+ * reach a slotted control through props — the wrapper never rendered it — so
+ * before this existed the caller copied three attributes by hand at every call
+ * site, and forgetting one was a silent accessibility defect.
+ *
+ * Every member is a `ComputedRef` rather than a value. A row's `error` arrives
+ * and clears while the control stays mounted, so the context has to move with
+ * it; and a per-key ref is what lets one wrapper inherit a single key from
+ * another (Field reads `readonly` off a Fieldset above it) without a hidden
+ * whole-object merge.
+ *
+ * On the booleans, `undefined` means "this wrapper has no opinion" and never
+ * "false". That is the whole precedence story — see `useFieldControl` — and it
+ * is the same distinction `./props.ts` exists to explain, arriving from the
+ * other side: there, a key is dropped so a child sees an absence; here, an
+ * absence is a value a wrapper is allowed to hold.
+ */
+export interface FieldContext {
+    /** The id the primary control adopts, so the wrapper's `<label for>` names it. */
+    readonly controlId: ComputedRef<string | undefined>;
+    /** The id of the wrapper's `<label>`, for group controls to reference via `aria-labelledby`. */
+    readonly labelledBy: ComputedRef<string | undefined>;
+    /** The id of the hint-or-error line, and `undefined` while no message is rendered. */
+    readonly describedBy: ComputedRef<string | undefined>;
+    /** The form field name the control submits under. */
+    readonly name: ComputedRef<string | undefined>;
+    /** Whether the wrapper marks the row mandatory. Becomes `aria-required`. */
+    readonly required: ComputedRef<boolean | undefined>;
+    /** Whether the wrapper is showing an error, which is the same fact as the control being invalid. */
+    readonly invalid: ComputedRef<boolean | undefined>;
+    /** Whether the wrapper disables what is inside it. */
+    readonly disabled: ComputedRef<boolean | undefined>;
+    /** Whether the wrapper renders what is inside it read-only. */
+    readonly readonly: ComputedRef<boolean | undefined>;
+    /**
+     * Claims the row's single control id, and reports whether this control won it.
+     *
+     * `<Field><TextField /><TextField /></Field>` is a shape somebody will write,
+     * and without a claim both inputs adopt the same generated id — a duplicate
+     * id, and a `<label for>` that resolves to whichever the browser reaches
+     * first. The `axe` gate cannot be the backstop: `duplicate-id-active` is
+     * tagged `wcag2a-obsolete`/`deprecated` in axe-core, not `wcag2a`, so it does
+     * not match `WCAG_TAGS` and `e2e/accessibility.e2e.ts` never runs it.
+     *
+     * Reactive rather than a plain boolean because the claim can move: a `v-if`
+     * swapping the first control for the second must promote the second, or the
+     * label points at an id no longer in the document.
+     */
+    claimControlId(): ComputedRef<boolean>;
+}
+/**
+ * What a wrapper hands `provideFieldContext`, as getters rather than values —
+ * the wrapper writes plain expressions over its own props and this file does
+ * the wrapping, so a wrapper never has to remember which of its answers are
+ * derived.
+ */
+export interface FieldContextSource {
+    controlId: () => string | undefined;
+    labelledBy?: () => string | undefined;
+    describedBy: () => string | undefined;
+    name: () => string | undefined;
+    required: () => boolean | undefined;
+    invalid: () => boolean | undefined;
+    disabled: () => boolean | undefined;
+    readonly: () => boolean | undefined;
+}
+/**
+ * The control's own side of the contract: what this control was told directly,
+ * with `undefined` for everything the caller left unset.
+ *
+ * Each key is `?: T | undefined` rather than `?: T`. Under
+ * `exactOptionalPropertyTypes` that is the form that accepts both an omitted
+ * key and an explicit `undefined` — and an explicit `undefined` is exactly what
+ * a control passes when its own prop is unset.
+ */
+export interface FieldControlProps {
+    /** The caller's `id`, which reaches a bare control as a fallthrough attr rather than a prop. */
+    readonly id?: string | undefined;
+    /** The caller's `aria-describedby`, likewise a fallthrough attr. */
+    readonly describedBy?: string | undefined;
+    /** The caller's `aria-labelledby`, for group controls that name themselves rather than being named by `label for`. */
+    readonly ariaLabelledby?: string | undefined;
+    readonly name?: string | undefined;
+    readonly required?: boolean | undefined;
+    readonly invalid?: boolean | undefined;
+    readonly disabled?: boolean | undefined;
+    readonly readonly?: boolean | undefined;
+}
+/**
+ * The resolved attributes, ready to spread onto whichever node carries the
+ * control's ARIA.
+ *
+ * A key whose value resolved to `undefined` is **absent**, not present-and-
+ * undefined — `optional()` drops it. That is what makes the spread purely
+ * additive: `v-bind="{ ...rest, ...field.attrs }"` can never blank out an
+ * attribute the caller passed through fallthrough, so a control renders exactly
+ * what it renders today whenever there is no wrapper above it.
+ *
+ * `aria-required` and `aria-invalid` are omitted rather than set to `"false"`.
+ * Both are legal and both say nothing, and the absent attribute already means
+ * the same thing — the house `x || undefined` idiom, moved one layer in.
+ */
+export interface FieldControlAttrs {
+    readonly id?: string;
+    readonly name?: string;
+    readonly "aria-describedby"?: string;
+    readonly "aria-required"?: "true";
+    readonly "aria-invalid"?: "true";
+}
+/**
+ * What `useFieldControl` resolved, after the control's own props won.
+ *
+ * Returned `reactive` rather than as a bag of refs, which is the one place in
+ * `src/lib/` that does so. A template unwraps only a *top-level* ref, and a
+ * control needs four of these at once under names — `disabled`, `invalid`,
+ * `readonly`, `required` — that each shadow a prop of the same name. `reactive`
+ * gives `field.invalid` in both the script and the template, and the shadowing
+ * question never arises. Destructuring it does lose reactivity; read through
+ * `field.` and there is nothing to get wrong.
+ */
+export interface FieldControl {
+    /** Spread onto the node that carries the control's ARIA, **after** the fallthrough attrs. */
+    readonly attrs: FieldControlAttrs;
+    readonly id: string | undefined;
+    readonly labelledBy: string | undefined;
+    readonly name: string | undefined;
+    readonly disabled: boolean;
+    readonly invalid: boolean;
+    readonly readonly: boolean;
+    readonly required: boolean;
+}
+/**
+ * The wrapper above this one, for a wrapper that composes over another.
+ *
+ * Only Field needs it, and only for `readonly`: Vue resolves `inject` to the
+ * nearest provider **wholesale**, not per key, so a Field shadows the Fieldset
+ * above it entirely. Any key both wrappers answer has to be merged by hand, and
+ * reading the outer context here rather than merging inside
+ * `provideFieldContext` keeps that decision visible in Field.vue, where the
+ * reason for it lives.
+ */
+export declare function useOuterFieldContext(): FieldContext | undefined;
+/** Called by a wrapper — Field and Fieldset — from its own `setup`. */
+export declare function provideFieldContext(source: FieldContextSource): void;
+/**
+ * Opt a control into the wrapper around it. One call, one spread — see
+ * `TextField.vue`, which is the worked example the rest of the family copies.
+ *
+ * **The rule is `own ?? wrapper ?? false`.** `??` and not `||`, so an explicit
+ * `false` on the control beats a `true` from the wrapper: one control inside a
+ * row that is showing an error can declare itself individually fine, and one
+ * inside a clean row can declare itself individually invalid.
+ *
+ * That rule is worth nothing unless "unset" and "set to `false`" are still
+ * different values by the time they arrive here, and by default they are not:
+ * Vue resolves an absent `Boolean` prop with no declared default to `false`, so
+ * `props.invalid ?? field` would short-circuit forever and the context would be
+ * inert while looking perfectly wired. **Every participating prop must be
+ * declared `boolean | undefined` with an explicit `undefined` default** — the
+ * `| undefined` is what `exactOptionalPropertyTypes` needs to let `withDefaults`
+ * take that default at all, and the default is what beats the Boolean cast.
+ *
+ * With no wrapper above, every chain falls through to the control's own props
+ * and the `?? false` at the end is the same `false` the control's `withDefaults`
+ * used to supply. Nothing about a control standing alone changes.
+ *
+ * The argument is a **getter**, not a props object, for the reason
+ * `./attrs.ts` takes `useAttrs()` rather than a snapshot: a control feeds this a
+ * mix of props and fallthrough attrs and both have to stay live.
+ */
+export declare function useFieldControl(own: () => FieldControlProps): FieldControl;
+//# sourceMappingURL=field-context.d.ts.map

package/dist/lib/field-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-context.d.ts","sourceRoot":"","sources":["../../src/lib/field-context.ts"],"names":[],"mappings":"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"}

package/dist/lib/field-context.js

@@ -0,0 +1,106 @@
+import { optional } from "./props.js";
+import { computed, inject, onScopeDispose, provide, reactive, ref } from "vue";
+//#region src/lib/field-context.ts
+/**
+* A `Symbol`, and not exported from `src/index.ts`: a consumer pinned to the
+* key is pinned to a shape that moves whenever a wrapper does. `useFieldControl`
+* is the supported way in.
+*/
+var FIELD_CONTEXT = Symbol("loom.field");
+/**
+* The wrapper above this one, for a wrapper that composes over another.
+*
+* Only Field needs it, and only for `readonly`: Vue resolves `inject` to the
+* nearest provider **wholesale**, not per key, so a Field shadows the Fieldset
+* above it entirely. Any key both wrappers answer has to be merged by hand, and
+* reading the outer context here rather than merging inside
+* `provideFieldContext` keeps that decision visible in Field.vue, where the
+* reason for it lives.
+*/
+function useOuterFieldContext() {
+	return inject(FIELD_CONTEXT, void 0);
+}
+/** Called by a wrapper — Field and Fieldset — from its own `setup`. */
+function provideFieldContext(source) {
+	const claims = ref([]);
+	provide(FIELD_CONTEXT, {
+		controlId: computed(source.controlId),
+		labelledBy: computed(source.labelledBy ?? (() => void 0)),
+		describedBy: computed(source.describedBy),
+		name: computed(source.name),
+		required: computed(source.required),
+		invalid: computed(source.invalid),
+		disabled: computed(source.disabled),
+		readonly: computed(source.readonly),
+		claimControlId() {
+			const token = Symbol("loom.field.control");
+			claims.value = [...claims.value, token];
+			onScopeDispose(() => {
+				claims.value = claims.value.filter((held) => held !== token);
+			});
+			return computed(() => claims.value[0] === token);
+		}
+	});
+}
+/**
+* Opt a control into the wrapper around it. One call, one spread — see
+* `TextField.vue`, which is the worked example the rest of the family copies.
+*
+* **The rule is `own ?? wrapper ?? false`.** `??` and not `||`, so an explicit
+* `false` on the control beats a `true` from the wrapper: one control inside a
+* row that is showing an error can declare itself individually fine, and one
+* inside a clean row can declare itself individually invalid.
+*
+* That rule is worth nothing unless "unset" and "set to `false`" are still
+* different values by the time they arrive here, and by default they are not:
+* Vue resolves an absent `Boolean` prop with no declared default to `false`, so
+* `props.invalid ?? field` would short-circuit forever and the context would be
+* inert while looking perfectly wired. **Every participating prop must be
+* declared `boolean | undefined` with an explicit `undefined` default** — the
+* `| undefined` is what `exactOptionalPropertyTypes` needs to let `withDefaults`
+* take that default at all, and the default is what beats the Boolean cast.
+*
+* With no wrapper above, every chain falls through to the control's own props
+* and the `?? false` at the end is the same `false` the control's `withDefaults`
+* used to supply. Nothing about a control standing alone changes.
+*
+* The argument is a **getter**, not a props object, for the reason
+* `./attrs.ts` takes `useAttrs()` rather than a snapshot: a control feeds this a
+* mix of props and fallthrough attrs and both have to stay live.
+*/
+function useFieldControl(own) {
+	const field = inject(FIELD_CONTEXT, void 0);
+	const holdsControlId = field?.claimControlId();
+	const id = computed(() => own().id ?? (holdsControlId?.value === true ? field?.controlId.value : void 0));
+	const name = computed(() => own().name ?? field?.name.value);
+	const labelledBy = computed(() => own().ariaLabelledby ?? field?.labelledBy.value);
+	const describedBy = computed(() => {
+		const ids = [own().describedBy, field?.describedBy.value].filter((candidate) => candidate !== void 0 && candidate.length > 0);
+		return ids.length > 0 ? ids.join(" ") : void 0;
+	});
+	const required = computed(() => own().required ?? field?.required.value ?? false);
+	const invalid = computed(() => own().invalid ?? field?.invalid.value ?? false);
+	const disabled = computed(() => own().disabled ?? field?.disabled.value ?? false);
+	const readonly = computed(() => own().readonly ?? field?.readonly.value ?? false);
+	const attrs = computed(() => optional({
+		id: id.value,
+		name: name.value,
+		"aria-describedby": describedBy.value,
+		"aria-required": required.value ? "true" : void 0,
+		"aria-invalid": invalid.value ? "true" : void 0
+	}));
+	return reactive({
+		attrs,
+		id,
+		labelledBy,
+		name,
+		disabled,
+		invalid,
+		readonly,
+		required
+	});
+}
+//#endregion
+export { provideFieldContext, useFieldControl, useOuterFieldContext };
+
+//# sourceMappingURL=field-context.js.map

package/dist/lib/field-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-context.js","names":[],"sources":["../../src/lib/field-context.ts"],"sourcesContent":["import {\n  computed,\n  inject,\n  onScopeDispose,\n  provide,\n  reactive,\n  ref,\n  watchEffect,\n  type ComputedRef,\n  type InjectionKey,\n} from \"vue\";\nimport { optional } from \"./props\";\n\n/**\n * What a form-row wrapper (Field, Fieldset) knows about the control inside it.\n *\n * A wrapper renders a `<label for>` and a hint-or-error line, and it is the\n * only thing in the tree that knows the id it pointed that label at, the id of\n * the message, and whether the row is mandatory or in error. None of that can\n * reach a slotted control through props — the wrapper never rendered it — so\n * before this existed the caller copied three attributes by hand at every call\n * site, and forgetting one was a silent accessibility defect.\n *\n * Every member is a `ComputedRef` rather than a value. A row's `error` arrives\n * and clears while the control stays mounted, so the context has to move with\n * it; and a per-key ref is what lets one wrapper inherit a single key from\n * another (Field reads `readonly` off a Fieldset above it) without a hidden\n * whole-object merge.\n *\n * On the booleans, `undefined` means \"this wrapper has no opinion\" and never\n * \"false\". That is the whole precedence story — see `useFieldControl` — and it\n * is the same distinction `./props.ts` exists to explain, arriving from the\n * other side: there, a key is dropped so a child sees an absence; here, an\n * absence is a value a wrapper is allowed to hold.\n */\nexport interface FieldContext {\n  /** The id the primary control adopts, so the wrapper's `<label for>` names it. */\n  readonly controlId: ComputedRef<string | undefined>;\n  /** The id of the wrapper's `<label>`, for group controls to reference via `aria-labelledby`. */\n  readonly labelledBy: ComputedRef<string | undefined>;\n  /** The id of the hint-or-error line, and `undefined` while no message is rendered. */\n  readonly describedBy: ComputedRef<string | undefined>;\n  /** The form field name the control submits under. */\n  readonly name: ComputedRef<string | undefined>;\n  /** Whether the wrapper marks the row mandatory. Becomes `aria-required`. */\n  readonly required: ComputedRef<boolean | undefined>;\n  /** Whether the wrapper is showing an error, which is the same fact as the control being invalid. */\n  readonly invalid: ComputedRef<boolean | undefined>;\n  /** Whether the wrapper disables what is inside it. */\n  readonly disabled: ComputedRef<boolean | undefined>;\n  /** Whether the wrapper renders what is inside it read-only. */\n  readonly readonly: ComputedRef<boolean | undefined>;\n  /**\n   * Claims the row's single control id, and reports whether this control won it.\n   *\n   * `<Field><TextField /><TextField /></Field>` is a shape somebody will write,\n   * and without a claim both inputs adopt the same generated id — a duplicate\n   * id, and a `<label for>` that resolves to whichever the browser reaches\n   * first. The `axe` gate cannot be the backstop: `duplicate-id-active` is\n   * tagged `wcag2a-obsolete`/`deprecated` in axe-core, not `wcag2a`, so it does\n   * not match `WCAG_TAGS` and `e2e/accessibility.e2e.ts` never runs it.\n   *\n   * Reactive rather than a plain boolean because the claim can move: a `v-if`\n   * swapping the first control for the second must promote the second, or the\n   * label points at an id no longer in the document.\n   */\n  claimControlId(): ComputedRef<boolean>;\n}\n\n/**\n * What a wrapper hands `provideFieldContext`, as getters rather than values —\n * the wrapper writes plain expressions over its own props and this file does\n * the wrapping, so a wrapper never has to remember which of its answers are\n * derived.\n */\nexport interface FieldContextSource {\n  controlId: () => string | undefined;\n  labelledBy?: () => string | undefined;\n  describedBy: () => string | undefined;\n  name: () => string | undefined;\n  required: () => boolean | undefined;\n  invalid: () => boolean | undefined;\n  disabled: () => boolean | undefined;\n  readonly: () => boolean | undefined;\n}\n\n/**\n * The control's own side of the contract: what this control was told directly,\n * with `undefined` for everything the caller left unset.\n *\n * Each key is `?: T | undefined` rather than `?: T`. Under\n * `exactOptionalPropertyTypes` that is the form that accepts both an omitted\n * key and an explicit `undefined` — and an explicit `undefined` is exactly what\n * a control passes when its own prop is unset.\n */\nexport interface FieldControlProps {\n  /** The caller's `id`, which reaches a bare control as a fallthrough attr rather than a prop. */\n  readonly id?: string | undefined;\n  /** The caller's `aria-describedby`, likewise a fallthrough attr. */\n  readonly describedBy?: string | undefined;\n  /** The caller's `aria-labelledby`, for group controls that name themselves rather than being named by `label for`. */\n  readonly ariaLabelledby?: string | undefined;\n  readonly name?: string | undefined;\n  readonly required?: boolean | undefined;\n  readonly invalid?: boolean | undefined;\n  readonly disabled?: boolean | undefined;\n  readonly readonly?: boolean | undefined;\n}\n\n/**\n * The resolved attributes, ready to spread onto whichever node carries the\n * control's ARIA.\n *\n * A key whose value resolved to `undefined` is **absent**, not present-and-\n * undefined — `optional()` drops it. That is what makes the spread purely\n * additive: `v-bind=\"{ ...rest, ...field.attrs }\"` can never blank out an\n * attribute the caller passed through fallthrough, so a control renders exactly\n * what it renders today whenever there is no wrapper above it.\n *\n * `aria-required` and `aria-invalid` are omitted rather than set to `\"false\"`.\n * Both are legal and both say nothing, and the absent attribute already means\n * the same thing — the house `x || undefined` idiom, moved one layer in.\n */\nexport interface FieldControlAttrs {\n  readonly id?: string;\n  readonly name?: string;\n  readonly \"aria-describedby\"?: string;\n  // Narrowed to the literal rather than `string`: Vue types `aria-invalid` on a\n  // native element as `Booleanish | \"grammar\" | \"spelling\"`, so a widened\n  // `string` here fails to spread onto the very `<input>` this exists for.\n  readonly \"aria-required\"?: \"true\";\n  readonly \"aria-invalid\"?: \"true\";\n}\n\n/**\n * What `useFieldControl` resolved, after the control's own props won.\n *\n * Returned `reactive` rather than as a bag of refs, which is the one place in\n * `src/lib/` that does so. A template unwraps only a *top-level* ref, and a\n * control needs four of these at once under names — `disabled`, `invalid`,\n * `readonly`, `required` — that each shadow a prop of the same name. `reactive`\n * gives `field.invalid` in both the script and the template, and the shadowing\n * question never arises. Destructuring it does lose reactivity; read through\n * `field.` and there is nothing to get wrong.\n */\nexport interface FieldControl {\n  /** Spread onto the node that carries the control's ARIA, **after** the fallthrough attrs. */\n  readonly attrs: FieldControlAttrs;\n  readonly id: string | undefined;\n  readonly labelledBy: string | undefined;\n  readonly name: string | undefined;\n  readonly disabled: boolean;\n  readonly invalid: boolean;\n  readonly readonly: boolean;\n  readonly required: boolean;\n}\n\n/**\n * A `Symbol`, and not exported from `src/index.ts`: a consumer pinned to the\n * key is pinned to a shape that moves whenever a wrapper does. `useFieldControl`\n * is the supported way in.\n */\nconst FIELD_CONTEXT: InjectionKey<FieldContext> = Symbol(\"loom.field\");\n\n/**\n * The wrapper above this one, for a wrapper that composes over another.\n *\n * Only Field needs it, and only for `readonly`: Vue resolves `inject` to the\n * nearest provider **wholesale**, not per key, so a Field shadows the Fieldset\n * above it entirely. Any key both wrappers answer has to be merged by hand, and\n * reading the outer context here rather than merging inside\n * `provideFieldContext` keeps that decision visible in Field.vue, where the\n * reason for it lives.\n */\nexport function useOuterFieldContext(): FieldContext | undefined {\n  return inject(FIELD_CONTEXT, undefined);\n}\n\n/** Called by a wrapper — Field and Fieldset — from its own `setup`. */\nexport function provideFieldContext(source: FieldContextSource): void {\n  const claims = ref<symbol[]>([]);\n\n  provide(FIELD_CONTEXT, {\n    controlId: computed(source.controlId),\n    labelledBy: computed(source.labelledBy ?? (() => undefined)),\n    describedBy: computed(source.describedBy),\n    name: computed(source.name),\n    required: computed(source.required),\n    invalid: computed(source.invalid),\n    disabled: computed(source.disabled),\n    readonly: computed(source.readonly),\n    claimControlId() {\n      const token = Symbol(\"loom.field.control\");\n      claims.value = [...claims.value, token];\n      // The claiming scope is the control's, not the wrapper's, so this fires\n      // when that one control unmounts and the next in document order is\n      // promoted.\n      onScopeDispose(() => {\n        claims.value = claims.value.filter((held) => held !== token);\n      });\n      return computed(() => claims.value[0] === token);\n    },\n  });\n}\n\n/**\n * Opt a control into the wrapper around it. One call, one spread — see\n * `TextField.vue`, which is the worked example the rest of the family copies.\n *\n * **The rule is `own ?? wrapper ?? false`.** `??` and not `||`, so an explicit\n * `false` on the control beats a `true` from the wrapper: one control inside a\n * row that is showing an error can declare itself individually fine, and one\n * inside a clean row can declare itself individually invalid.\n *\n * That rule is worth nothing unless \"unset\" and \"set to `false`\" are still\n * different values by the time they arrive here, and by default they are not:\n * Vue resolves an absent `Boolean` prop with no declared default to `false`, so\n * `props.invalid ?? field` would short-circuit forever and the context would be\n * inert while looking perfectly wired. **Every participating prop must be\n * declared `boolean | undefined` with an explicit `undefined` default** — the\n * `| undefined` is what `exactOptionalPropertyTypes` needs to let `withDefaults`\n * take that default at all, and the default is what beats the Boolean cast.\n *\n * With no wrapper above, every chain falls through to the control's own props\n * and the `?? false` at the end is the same `false` the control's `withDefaults`\n * used to supply. Nothing about a control standing alone changes.\n *\n * The argument is a **getter**, not a props object, for the reason\n * `./attrs.ts` takes `useAttrs()` rather than a snapshot: a control feeds this a\n * mix of props and fallthrough attrs and both have to stay live.\n */\nexport function useFieldControl(own: () => FieldControlProps): FieldControl {\n  const field = inject(FIELD_CONTEXT, undefined);\n  const holdsControlId = field?.claimControlId();\n\n  const id = computed(\n    () => own().id ?? (holdsControlId?.value === true ? field?.controlId.value : undefined),\n  );\n  const name = computed(() => own().name ?? field?.name.value);\n  const labelledBy = computed(() => own().ariaLabelledby ?? field?.labelledBy.value);\n\n  // The one attribute whose rule is merge rather than replace, because\n  // `aria-describedby` is a token list: the row's message is additional to\n  // whatever else the caller pointed at, not an alternative to it. Replacing\n  // would silently drop the row's hint the moment a caller described their\n  // control for some other reason — which is the defect this file exists to\n  // remove, reintroduced from the other end. The control's own id reads first:\n  // a control that has something to say about itself is saying the more\n  // specific thing, and a screen reader reads the list in order.\n  const describedBy = computed(() => {\n    const ids = [own().describedBy, field?.describedBy.value].filter(\n      (candidate): candidate is string => candidate !== undefined && candidate.length > 0,\n    );\n    return ids.length > 0 ? ids.join(\" \") : undefined;\n  });\n\n  const required = computed(() => own().required ?? field?.required.value ?? false);\n  const invalid = computed(() => own().invalid ?? field?.invalid.value ?? false);\n  const disabled = computed(() => own().disabled ?? field?.disabled.value ?? false);\n  const readonly = computed(() => own().readonly ?? field?.readonly.value ?? false);\n\n  // A development-mode safety net for the one context key a control can\n  // deliberately decline. When a wrapper sets `readonly` but the control did\n  // not pass that key in its `FieldControlProps`, the wrapper's instruction is\n  // silently dropped — and without this warning the consumer has no signal\n  // that it was. The `\"readonly\" in own()` check distinguishes \"I defer to the\n  // wrapper\" (key present, value `undefined`) from \"I don't participate\" (key\n  // absent), which is the same distinction `exactOptionalPropertyTypes` makes\n  // at the type level.\n  if (import.meta.env.DEV && field) {\n    watchEffect(() => {\n      if (field.readonly.value && !(\"readonly\" in own())) {\n        console.warn(\"[Loom] readonly was set on the Field, but this control does not claim it.\");\n      }\n    });\n  }\n\n  const attrs = computed<FieldControlAttrs>(() =>\n    optional({\n      id: id.value,\n      name: name.value,\n      \"aria-describedby\": describedBy.value,\n      \"aria-required\": required.value ? (\"true\" as const) : undefined,\n      \"aria-invalid\": invalid.value ? (\"true\" as const) : undefined,\n    }),\n  );\n\n  return reactive({ attrs, id, labelledBy, name, disabled, invalid, readonly, required });\n}\n"],"mappings":";;;;;;;;AAkKA,IAAM,gBAA4C,OAAO,YAAY;;;;;;;;;;;AAYrE,SAAgB,uBAAiD;CAC/D,OAAO,OAAO,eAAe,KAAA,CAAS;AACxC;;AAGA,SAAgB,oBAAoB,QAAkC;CACpE,MAAM,SAAS,IAAc,CAAC,CAAC;CAE/B,QAAQ,eAAe;EACrB,WAAW,SAAS,OAAO,SAAS;EACpC,YAAY,SAAS,OAAO,qBAAqB,KAAA,EAAU;EAC3D,aAAa,SAAS,OAAO,WAAW;EACxC,MAAM,SAAS,OAAO,IAAI;EAC1B,UAAU,SAAS,OAAO,QAAQ;EAClC,SAAS,SAAS,OAAO,OAAO;EAChC,UAAU,SAAS,OAAO,QAAQ;EAClC,UAAU,SAAS,OAAO,QAAQ;EAClC,iBAAiB;GACf,MAAM,QAAQ,OAAO,oBAAoB;GACzC,OAAO,QAAQ,CAAC,GAAG,OAAO,OAAO,KAAK;GAItC,qBAAqB;IACnB,OAAO,QAAQ,OAAO,MAAM,QAAQ,SAAS,SAAS,KAAK;GAC7D,CAAC;GACD,OAAO,eAAe,OAAO,MAAM,OAAO,KAAK;EACjD;CACF,CAAC;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,SAAgB,gBAAgB,KAA4C;CAC1E,MAAM,QAAQ,OAAO,eAAe,KAAA,CAAS;CAC7C,MAAM,iBAAiB,OAAO,eAAe;CAE7C,MAAM,KAAK,eACH,IAAI,CAAC,CAAC,OAAO,gBAAgB,UAAU,OAAO,OAAO,UAAU,QAAQ,KAAA,EAC/E;CACA,MAAM,OAAO,eAAe,IAAI,CAAC,CAAC,QAAQ,OAAO,KAAK,KAAK;CAC3D,MAAM,aAAa,eAAe,IAAI,CAAC,CAAC,kBAAkB,OAAO,WAAW,KAAK;CAUjF,MAAM,cAAc,eAAe;EACjC,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC,aAAa,OAAO,YAAY,KAAK,CAAC,CAAC,QACvD,cAAmC,cAAc,KAAA,KAAa,UAAU,SAAS,CACpF;EACA,OAAO,IAAI,SAAS,IAAI,IAAI,KAAK,GAAG,IAAI,KAAA;CAC1C,CAAC;CAED,MAAM,WAAW,eAAe,IAAI,CAAC,CAAC,YAAY,OAAO,SAAS,SAAS,KAAK;CAChF,MAAM,UAAU,eAAe,IAAI,CAAC,CAAC,WAAW,OAAO,QAAQ,SAAS,KAAK;CAC7E,MAAM,WAAW,eAAe,IAAI,CAAC,CAAC,YAAY,OAAO,SAAS,SAAS,KAAK;CAChF,MAAM,WAAW,eAAe,IAAI,CAAC,CAAC,YAAY,OAAO,SAAS,SAAS,KAAK;CAkBhF,MAAM,QAAQ,eACZ,SAAS;EACP,IAAI,GAAG;EACP,MAAM,KAAK;EACX,oBAAoB,YAAY;EAChC,iBAAiB,SAAS,QAAS,SAAmB,KAAA;EACtD,gBAAgB,QAAQ,QAAS,SAAmB,KAAA;CACtD,CAAC,CACH;CAEA,OAAO,SAAS;EAAE;EAAO;EAAI;EAAY;EAAM;EAAU;EAAS;EAAU;CAAS,CAAC;AACxF"}

package/dist/lib/label-registry.d.ts

@@ -0,0 +1,75 @@
+import type { CalendarPanelLabels, DateSegmentLabels, RangeCellLabels, TimeSegmentLabels } from "./date-labels";
+import type { DateRangeLabels } from "../primitives/DateRangePicker/DateRangePicker.vue";
+import type { DateTimeRangeLabels } from "../primitives/DateTimeRangePicker/DateTimeRangePicker.vue";
+import type { ComboboxLabels } from "../primitives/Combobox/Combobox.vue";
+import type { EditableLabels } from "../primitives/Editable/Editable.vue";
+import type { FileUploadLabels } from "../primitives/FileUpload/FileUpload.vue";
+import type { NumberFieldLabels } from "../primitives/NumberField/NumberField.vue";
+import type { OtpInputLabels } from "../primitives/OtpInput/OtpInput.vue";
+import type { PaginationLabels } from "../primitives/Pagination/Pagination.vue";
+import type { RatingLabels } from "../primitives/Rating/Rating.vue";
+import type { WindowControlsLabels } from "../primitives/WindowControls/WindowControls.vue";
+import type { AvatarGroupLabels } from "../primitives/AvatarGroup/AvatarGroup.vue";
+import type { ColorPickerLabels } from "../primitives/ColorPicker/ColorPicker.vue";
+import type { IndicatorLabels } from "../primitives/Indicator/Indicator.vue";
+import type { ProgressLabels } from "../primitives/Progress/Progress.vue";
+import type { RadialProgressLabels } from "../primitives/RadialProgress/RadialProgress.vue";
+import type { AlertDialogLabels } from "../primitives/AlertDialog/AlertDialog.vue";
+import type { DialogLabels } from "../primitives/Dialog/Dialog.vue";
+import type { DrawerLabels } from "../primitives/Drawer/Drawer.vue";
+import type { StepperLabels } from "../primitives/Stepper/Stepper.vue";
+import type { ToastLabels } from "../primitives/Toast/Toast.vue";
+import type { TagsInputLabels } from "../primitives/TagsInput/TagsInput.vue";
+import type { TextFieldLabels } from "../primitives/TextField/TextField.vue";
+import type { TextareaLabels } from "../primitives/Textarea/Textarea.vue";
+/**
+ * Every slot a host can localise, and nothing else. One line per component that
+ * speaks; the keys themselves live with the component that says them.
+ *
+ * This file exists so that both halves of the seam can be true at once. The
+ * *keys* belong beside the component — `PaginationLabels` is declared in
+ * `Pagination.vue`, where its doc comments sit next to the markup that renders
+ * them and where a component's whole contract can be read in one file. The
+ * *namespace* has to be central, or `provideLoomLabels({ pagination: … })` could
+ * not check a misspelled slot and a consumer would have no single place to see
+ * what the library can be asked to say.
+ *
+ * Every import here is `import type`, so this module emits nothing and the
+ * apparent cycle — component imports `useLabels`, `useLabels` imports this,
+ * this imports the component — exists only in the type graph, where TypeScript
+ * resolves it lazily. A value import in this file would turn the whole library
+ * into one chunk and cost every consumer the components they did not use.
+ *
+ * Adding a component to the sweep is one line. Adding it in the wrong shape is
+ * a compile error at that component's own `useLabels` call, not here.
+ */
+export interface LoomLabels {
+    readonly pagination: PaginationLabels;
+    readonly windowControls: WindowControlsLabels;
+    readonly dateSegments: DateSegmentLabels;
+    readonly timeSegments: TimeSegmentLabels;
+    readonly calendarPanel: CalendarPanelLabels;
+    readonly rangeCell: RangeCellLabels;
+    readonly dateRange: DateRangeLabels;
+    readonly dateTimeRange: DateTimeRangeLabels;
+    readonly numberField: NumberFieldLabels;
+    readonly combobox: ComboboxLabels;
+    readonly otpInput: OtpInputLabels;
+    readonly fileUpload: FileUploadLabels;
+    readonly rating: RatingLabels;
+    readonly tagsInput: TagsInputLabels;
+    readonly editable: EditableLabels;
+    readonly textField: TextFieldLabels;
+    readonly textarea: TextareaLabels;
+    readonly dialog: DialogLabels;
+    readonly alertDialog: AlertDialogLabels;
+    readonly drawer: DrawerLabels;
+    readonly stepper: StepperLabels;
+    readonly toast: ToastLabels;
+    readonly indicator: IndicatorLabels;
+    readonly avatarGroup: AvatarGroupLabels;
+    readonly progress: ProgressLabels;
+    readonly radialProgress: RadialProgressLabels;
+    readonly colorPicker: ColorPickerLabels;
+}
+//# sourceMappingURL=label-registry.d.ts.map

package/dist/lib/label-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"label-registry.d.ts","sourceRoot":"","sources":["../../src/lib/label-registry.ts"],"names":[],"mappings":"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"}

package/dist/lib/labels.d.ts

@@ -0,0 +1,116 @@
+import { type ComputedRef } from "vue";
+import type { LoomLabels } from "./label-registry";
+/**
+ * A message the component cannot write on its own, because it depends on a
+ * value only the render knows — a page number, a file name, a count.
+ *
+ * **The argument is one object, and every member is a raw value: a `number`, a
+ * `Date`, a `File`. Never a string Loom has already formatted.** That is the
+ * entire pluralisation answer, and it is why this library ships no
+ * pluralisation engine and takes no i18n dependency. "3 unread" has one form in
+ * Vietnamese, two in English, three in Russian and six in Arabic, and no
+ * placeholder syntax Loom could invent would carry that. Loom hands over the
+ * facts and receives a finished string; selecting the plural category, shaping
+ * the digits and ordering the sentence all happen in the consumer's own
+ * `Intl.PluralRules`, `Intl.NumberFormat`, vue-i18n, or hand-written `if`.
+ *
+ * Hand over the number and a consumer can reach `Intl.NumberFormat` for Eastern
+ * Arabic digits. Hand over `"3"` and they cannot: the decision was already made,
+ * in English, inside a component that had no business making it.
+ *
+ * One object rather than positional parameters, for two reasons. A bare
+ * `(4, 12)` in a consumer's locale file says nothing about what either number
+ * is. And a fact added later is a new key an existing override simply ignores,
+ * where a new positional parameter would silently re-order every call site.
+ *
+ * There is deliberately no third kind. A message is a `string` or it is one of
+ * these; a `string | (() => string)` union was considered and rejected, because
+ * the reactivity it exists to buy is already bought by `provideLoomLabels`
+ * taking a getter — and it would put a `resolve()` call around every binding in
+ * every component for the rest of the library's life.
+ */
+export type LabelOf<Args extends object> = (args: Args) => string;
+/**
+ * What a consumer may pass for one component's bag: any subset of it.
+ *
+ * **This, not the bag interface itself, is the type a consumer annotates their
+ * own object with.** A bag typed `PaginationLabels` must answer every key, so a
+ * key added in a later release breaks that consumer's build; a bag typed
+ * `LabelOverrides<PaginationLabels>` does not, which is what makes growing the
+ * vocabulary a `feat` rather than a `feat!`.
+ *
+ * `T[K] | undefined` rather than a plain `Partial<T>`, because
+ * `exactOptionalPropertyTypes` is on: under it `Partial<T>` rejects an
+ * explicitly-`undefined` value, and an explicit `undefined` is exactly what a
+ * consumer's own conditional expression produces when its condition is unmet.
+ * It has to mean "no opinion", never "blank this out" — the same distinction
+ * `./props.ts` exists to explain, arriving one layer in.
+ */
+export type LabelOverrides<T extends object> = {
+    readonly [K in keyof T]?: T[K] | undefined;
+};
+/**
+ * A whole vocabulary, as a host supplies it: any subset of any slot.
+ *
+ * Both levels are partial and both are checked. A misspelled slot and a
+ * misspelled key inside a slot are each a compile error — on a fresh object
+ * literal, which is the caveat the localisation guide documents and the reason
+ * it tells a consumer to write `satisfies LoomLabelOverrides` on a bag they
+ * hoist to a module.
+ */
+export type LoomLabelOverrides = {
+    readonly [K in keyof LoomLabels]?: LabelOverrides<LoomLabels[K]> | undefined;
+};
+/**
+ * Declare a host's vocabulary once, from the `setup` of its root component —
+ * the same place, and for the same reason, as `applyLoomIconDefaults`. It
+ * resolves to Vue's `provide()`, so called from a plain entry module it
+ * silently provides nothing and every component keeps its English.
+ *
+ * A **getter**, not a value, for the reason `./attrs.ts` takes `useAttrs()`
+ * rather than a snapshot: the getter runs inside the `computed` that
+ * `useLabels` returns, which runs inside the render effect, so a host whose bag
+ * reads `t("pager.next")` tracks their locale ref and every Loom component
+ * repaints on a language switch with no work here at all. Snapshot the bag
+ * instead and the first language renders correctly and every switch after it
+ * does nothing — a failure with no error and no warning.
+ *
+ * **A nested call merges into the bag above it rather than replacing it**, and
+ * that is a deliberate divergence from `./field-context.ts`, which documents
+ * the opposite and hand-merges the single key that needs it. Vue resolves
+ * `inject` wholesale to the nearest provider, so without this a host wrapping
+ * one dialog in a second `provideLoomLabels` to change one string would lose
+ * every other string in the application back to English. Hand-merging is right
+ * for two wrappers and one key; it does not scale to a vocabulary this size at
+ * an unknown depth.
+ */
+export declare function provideLoomLabels(source: () => LoomLabelOverrides): void;
+/**
+ * Resolve one component's slot: **own prop, then the host's vocabulary, then
+ * the component's own English** — key by key, never whole-object.
+ *
+ * Key by key is the whole point. A host providing `{ pagination: { next: "Sau" } }`
+ * keeps English for the other seven rather than rendering a row of unnamed
+ * buttons, and an instance overriding its own `nav` does not discard the host's
+ * other six. `optional()` is what makes each spread purely additive: it drops
+ * the `undefined`-valued keys, so an absent override cannot blank a present
+ * default. Same function, same reasoning, as the attribute spread in
+ * `./field-context.ts`.
+ *
+ * The prop beating the provider is not a preference. A page with two paginations
+ * that need different names has no other way out, and an application-wide
+ * vocabulary that could not be corrected per instance would force a host to
+ * choose between localising and naming.
+ *
+ * `defaults` arrives from the component rather than from a central English
+ * bundle, and that is what bounds the cost of the seam: a consumer importing
+ * only `Button` ships no label bytes at all, and one importing `Pagination`
+ * ships `Pagination`'s. A central `en` object would always ship whole.
+ *
+ * The result is typed from `defaults` rather than from `LoomLabels[K]`, with
+ * the registry entry as a constraint on it. Structurally that is the same
+ * check — a bag that does not match its registered slot does not compile — but
+ * it keeps the resolved type nameable from the module that declared it.
+ */
+export declare function useLabels<K extends keyof LoomLabels, T extends LoomLabels[K]>(slot: K, defaults: T, own?: () => LabelOverrides<T> | undefined): ComputedRef<LoomLabels[K]>;
+//# sourceMappingURL=labels.d.ts.map

package/dist/lib/labels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"labels.d.ts","sourceRoot":"","sources":["../../src/lib/labels.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6B,KAAK,WAAW,EAAqB,MAAM,KAAK,CAAC;AAErF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,MAAM,OAAO,CAAC,IAAI,SAAS,MAAM,IAAI,CAAC,IAAI,EAAE,IAAI,KAAK,MAAM,CAAC;AAElE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,MAAM,IAAI;IAC7C,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS;CAC3C,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,EAAE,CAAC,IAAI,MAAM,UAAU,CAAC,CAAC,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,SAAS;CAC7E,CAAC;AA4BF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,kBAAkB,GAAG,IAAI,CAMxE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,UAAU,EAAE,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,EAC3E,IAAI,EAAE,CAAC,EACP,QAAQ,EAAE,CAAC,EACX,GAAG,CAAC,EAAE,MAAM,cAAc,CAAC,CAAC,CAAC,GAAG,SAAS,GACxC,WAAW,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAa5B"}

package/dist/lib/labels.js

@@ -0,0 +1,84 @@
+import { optional } from "./props.js";
+import { computed, inject, provide } from "vue";
+//#region src/lib/labels.ts
+/**
+* A `Symbol`, and not exported from `src/index.ts`, for the reason
+* `./field-context.ts` gives about its own: a consumer pinned to the key is
+* pinned to a shape that moves. `provideLoomLabels` is the supported way in.
+*/
+var LOOM_LABELS = Symbol("loom.labels");
+function mergeVocabularies(outer, inner) {
+	const merged = { ...outer };
+	const patches = inner;
+	for (const slot of Object.keys(patches)) {
+		const patch = patches[slot];
+		if (patch === void 0) continue;
+		merged[slot] = {
+			...merged[slot] ?? {},
+			...optional(patch)
+		};
+	}
+	return merged;
+}
+/**
+* Declare a host's vocabulary once, from the `setup` of its root component —
+* the same place, and for the same reason, as `applyLoomIconDefaults`. It
+* resolves to Vue's `provide()`, so called from a plain entry module it
+* silently provides nothing and every component keeps its English.
+*
+* A **getter**, not a value, for the reason `./attrs.ts` takes `useAttrs()`
+* rather than a snapshot: the getter runs inside the `computed` that
+* `useLabels` returns, which runs inside the render effect, so a host whose bag
+* reads `t("pager.next")` tracks their locale ref and every Loom component
+* repaints on a language switch with no work here at all. Snapshot the bag
+* instead and the first language renders correctly and every switch after it
+* does nothing — a failure with no error and no warning.
+*
+* **A nested call merges into the bag above it rather than replacing it**, and
+* that is a deliberate divergence from `./field-context.ts`, which documents
+* the opposite and hand-merges the single key that needs it. Vue resolves
+* `inject` wholesale to the nearest provider, so without this a host wrapping
+* one dialog in a second `provideLoomLabels` to change one string would lose
+* every other string in the application back to English. Hand-merging is right
+* for two wrappers and one key; it does not scale to a vocabulary this size at
+* an unknown depth.
+*/
+function provideLoomLabels(source) {
+	const outer = inject(LOOM_LABELS, void 0);
+	provide(LOOM_LABELS, computed(() => outer === void 0 ? source() : mergeVocabularies(outer.value, source())));
+}
+/**
+* Resolve one component's slot: **own prop, then the host's vocabulary, then
+* the component's own English** — key by key, never whole-object.
+*
+* Key by key is the whole point. A host providing `{ pagination: { next: "Sau" } }`
+* keeps English for the other seven rather than rendering a row of unnamed
+* buttons, and an instance overriding its own `nav` does not discard the host's
+* other six. `optional()` is what makes each spread purely additive: it drops
+* the `undefined`-valued keys, so an absent override cannot blank a present
+* default. Same function, same reasoning, as the attribute spread in
+* `./field-context.ts`.
+*
+* The prop beating the provider is not a preference. A page with two paginations
+* that need different names has no other way out, and an application-wide
+* vocabulary that could not be corrected per instance would force a host to
+* choose between localising and naming.
+*
+* `defaults` arrives from the component rather than from a central English
+* bundle, and that is what bounds the cost of the seam: a consumer importing
+* only `Button` ships no label bytes at all, and one importing `Pagination`
+* ships `Pagination`'s. A central `en` object would always ship whole.
+*
+* The result is typed from `defaults` rather than from `LoomLabels[K]`, with
+* the registry entry as a constraint on it. Structurally that is the same
+* check — a bag that does not match its registered slot does not compile — but
+* it keeps the resolved type nameable from the module that declared it.
+*/
+function useLabels(slot, defaults, own) {
+	const provided = inject(LOOM_LABELS, void 0);
+	return computed(() => Object.assign({}, defaults, optional(provided?.value[slot] ?? {}), optional(own?.() ?? {})));
+}
+//#endregion
+export { provideLoomLabels, useLabels };
+
+//# sourceMappingURL=labels.js.map

package/dist/lib/labels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"labels.js","names":[],"sources":["../../src/lib/labels.ts"],"sourcesContent":["import { computed, inject, provide, type ComputedRef, type InjectionKey } from \"vue\";\nimport { optional } from \"./props\";\nimport type { LoomLabels } from \"./label-registry\";\n\n/**\n * A message the component cannot write on its own, because it depends on a\n * value only the render knows — a page number, a file name, a count.\n *\n * **The argument is one object, and every member is a raw value: a `number`, a\n * `Date`, a `File`. Never a string Loom has already formatted.** That is the\n * entire pluralisation answer, and it is why this library ships no\n * pluralisation engine and takes no i18n dependency. \"3 unread\" has one form in\n * Vietnamese, two in English, three in Russian and six in Arabic, and no\n * placeholder syntax Loom could invent would carry that. Loom hands over the\n * facts and receives a finished string; selecting the plural category, shaping\n * the digits and ordering the sentence all happen in the consumer's own\n * `Intl.PluralRules`, `Intl.NumberFormat`, vue-i18n, or hand-written `if`.\n *\n * Hand over the number and a consumer can reach `Intl.NumberFormat` for Eastern\n * Arabic digits. Hand over `\"3\"` and they cannot: the decision was already made,\n * in English, inside a component that had no business making it.\n *\n * One object rather than positional parameters, for two reasons. A bare\n * `(4, 12)` in a consumer's locale file says nothing about what either number\n * is. And a fact added later is a new key an existing override simply ignores,\n * where a new positional parameter would silently re-order every call site.\n *\n * There is deliberately no third kind. A message is a `string` or it is one of\n * these; a `string | (() => string)` union was considered and rejected, because\n * the reactivity it exists to buy is already bought by `provideLoomLabels`\n * taking a getter — and it would put a `resolve()` call around every binding in\n * every component for the rest of the library's life.\n */\nexport type LabelOf<Args extends object> = (args: Args) => string;\n\n/**\n * What a consumer may pass for one component's bag: any subset of it.\n *\n * **This, not the bag interface itself, is the type a consumer annotates their\n * own object with.** A bag typed `PaginationLabels` must answer every key, so a\n * key added in a later release breaks that consumer's build; a bag typed\n * `LabelOverrides<PaginationLabels>` does not, which is what makes growing the\n * vocabulary a `feat` rather than a `feat!`.\n *\n * `T[K] | undefined` rather than a plain `Partial<T>`, because\n * `exactOptionalPropertyTypes` is on: under it `Partial<T>` rejects an\n * explicitly-`undefined` value, and an explicit `undefined` is exactly what a\n * consumer's own conditional expression produces when its condition is unmet.\n * It has to mean \"no opinion\", never \"blank this out\" — the same distinction\n * `./props.ts` exists to explain, arriving one layer in.\n */\nexport type LabelOverrides<T extends object> = {\n  readonly [K in keyof T]?: T[K] | undefined;\n};\n\n/**\n * A whole vocabulary, as a host supplies it: any subset of any slot.\n *\n * Both levels are partial and both are checked. A misspelled slot and a\n * misspelled key inside a slot are each a compile error — on a fresh object\n * literal, which is the caveat the localisation guide documents and the reason\n * it tells a consumer to write `satisfies LoomLabelOverrides` on a bag they\n * hoist to a module.\n */\nexport type LoomLabelOverrides = {\n  readonly [K in keyof LoomLabels]?: LabelOverrides<LoomLabels[K]> | undefined;\n};\n\n/** The shape both merge steps work in, once the slot's identity has been checked. */\ntype AnyBag = Record<string, unknown>;\n\n/**\n * A `Symbol`, and not exported from `src/index.ts`, for the reason\n * `./field-context.ts` gives about its own: a consumer pinned to the key is\n * pinned to a shape that moves. `provideLoomLabels` is the supported way in.\n */\nconst LOOM_LABELS: InjectionKey<ComputedRef<LoomLabelOverrides>> = Symbol(\"loom.labels\");\n\nfunction mergeVocabularies(\n  outer: LoomLabelOverrides,\n  inner: LoomLabelOverrides,\n): LoomLabelOverrides {\n  const merged = { ...outer } as AnyBag;\n  const patches = inner as AnyBag;\n  for (const slot of Object.keys(patches)) {\n    const patch = patches[slot] as AnyBag | undefined;\n    if (patch === undefined) continue;\n    // Per key inside the slot as well as per slot: a nested provider changing\n    // one string must not blank the rest of that slot back to English.\n    merged[slot] = { ...((merged[slot] ?? {}) as AnyBag), ...optional(patch) };\n  }\n  return merged;\n}\n\n/**\n * Declare a host's vocabulary once, from the `setup` of its root component —\n * the same place, and for the same reason, as `applyLoomIconDefaults`. It\n * resolves to Vue's `provide()`, so called from a plain entry module it\n * silently provides nothing and every component keeps its English.\n *\n * A **getter**, not a value, for the reason `./attrs.ts` takes `useAttrs()`\n * rather than a snapshot: the getter runs inside the `computed` that\n * `useLabels` returns, which runs inside the render effect, so a host whose bag\n * reads `t(\"pager.next\")` tracks their locale ref and every Loom component\n * repaints on a language switch with no work here at all. Snapshot the bag\n * instead and the first language renders correctly and every switch after it\n * does nothing — a failure with no error and no warning.\n *\n * **A nested call merges into the bag above it rather than replacing it**, and\n * that is a deliberate divergence from `./field-context.ts`, which documents\n * the opposite and hand-merges the single key that needs it. Vue resolves\n * `inject` wholesale to the nearest provider, so without this a host wrapping\n * one dialog in a second `provideLoomLabels` to change one string would lose\n * every other string in the application back to English. Hand-merging is right\n * for two wrappers and one key; it does not scale to a vocabulary this size at\n * an unknown depth.\n */\nexport function provideLoomLabels(source: () => LoomLabelOverrides): void {\n  const outer = inject(LOOM_LABELS, undefined);\n  provide(\n    LOOM_LABELS,\n    computed(() => (outer === undefined ? source() : mergeVocabularies(outer.value, source()))),\n  );\n}\n\n/**\n * Resolve one component's slot: **own prop, then the host's vocabulary, then\n * the component's own English** — key by key, never whole-object.\n *\n * Key by key is the whole point. A host providing `{ pagination: { next: \"Sau\" } }`\n * keeps English for the other seven rather than rendering a row of unnamed\n * buttons, and an instance overriding its own `nav` does not discard the host's\n * other six. `optional()` is what makes each spread purely additive: it drops\n * the `undefined`-valued keys, so an absent override cannot blank a present\n * default. Same function, same reasoning, as the attribute spread in\n * `./field-context.ts`.\n *\n * The prop beating the provider is not a preference. A page with two paginations\n * that need different names has no other way out, and an application-wide\n * vocabulary that could not be corrected per instance would force a host to\n * choose between localising and naming.\n *\n * `defaults` arrives from the component rather than from a central English\n * bundle, and that is what bounds the cost of the seam: a consumer importing\n * only `Button` ships no label bytes at all, and one importing `Pagination`\n * ships `Pagination`'s. A central `en` object would always ship whole.\n *\n * The result is typed from `defaults` rather than from `LoomLabels[K]`, with\n * the registry entry as a constraint on it. Structurally that is the same\n * check — a bag that does not match its registered slot does not compile — but\n * it keeps the resolved type nameable from the module that declared it.\n */\nexport function useLabels<K extends keyof LoomLabels, T extends LoomLabels[K]>(\n  slot: K,\n  defaults: T,\n  own?: () => LabelOverrides<T> | undefined,\n): ComputedRef<LoomLabels[K]> {\n  const provided = inject(LOOM_LABELS, undefined);\n  // Read inside the `computed`, never above it: that is what puts the host's\n  // getter and this component's props inside the render effect, and it is the\n  // one line that decides whether a language switch repaints.\n  //\n  // `Object.assign` rather than an object spread, and that is a type-level\n  // choice rather than a stylistic one: spreading a generic `LoomLabels[K]`\n  // widens it to an index signature that no longer satisfies the return type,\n  // where `Object.assign` composes an intersection that does.\n  return computed(() =>\n    Object.assign({}, defaults, optional(provided?.value[slot] ?? {}), optional(own?.() ?? {})),\n  );\n}\n"],"mappings":";;;;;;;;AA4EA,IAAM,cAA6D,OAAO,aAAa;AAEvF,SAAS,kBACP,OACA,OACoB;CACpB,MAAM,SAAS,EAAE,GAAG,MAAM;CAC1B,MAAM,UAAU;CAChB,KAAK,MAAM,QAAQ,OAAO,KAAK,OAAO,GAAG;EACvC,MAAM,QAAQ,QAAQ;EACtB,IAAI,UAAU,KAAA,GAAW;EAGzB,OAAO,QAAQ;GAAE,GAAK,OAAO,SAAS,CAAC;GAAe,GAAG,SAAS,KAAK;EAAE;CAC3E;CACA,OAAO;AACT;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,SAAgB,kBAAkB,QAAwC;CACxE,MAAM,QAAQ,OAAO,aAAa,KAAA,CAAS;CAC3C,QACE,aACA,eAAgB,UAAU,KAAA,IAAY,OAAO,IAAI,kBAAkB,MAAM,OAAO,OAAO,CAAC,CAAE,CAC5F;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,SAAgB,UACd,MACA,UACA,KAC4B;CAC5B,MAAM,WAAW,OAAO,aAAa,KAAA,CAAS;CAS9C,OAAO,eACL,OAAO,OAAO,CAAC,GAAG,UAAU,SAAS,UAAU,MAAM,SAAS,CAAC,CAAC,GAAG,SAAS,MAAM,KAAK,CAAC,CAAC,CAAC,CAC5F;AACF"}