@ttoss/fsl-ui 0.2.4

package/dist/composites/Wizard/Wizard.d.mts

@@ -0,0 +1,206 @@
+
+import * as React from "react";
+
+//#region src/composites/Wizard/Wizard.d.ts
+type WizardSlotComposition = 'step' | 'summary' | 'navigation';
+type WizardSlotComponent<P, K extends WizardSlotComposition> = React.ComponentType<P> & {
+  composition: K;
+};
+/**
+ * Public state surface shared by the {@link Wizard} host with its
+ * sub-parts. Consumed by {@link WizardNavigationProps.children} as a
+ * render-prop signature so authors can compose custom navigation while
+ * still observing the same state machine the default row uses.
+ */
+interface WizardState {
+  currentStep: number;
+  totalSteps: number;
+  isFirst: boolean;
+  isLast: boolean;
+  isComplete: boolean;
+  goNext: () => void;
+  goPrev: () => void;
+  goTo: (step: number) => void;
+}
+/**
+ * Formal semantic identity — Wizard root (Structure entity, root part).
+ */
+declare const wizardMeta: {
+  readonly displayName: "Wizard";
+  readonly entity: "Structure";
+  readonly structure: "root";
+};
+/**
+ * Props for {@link Wizard}.
+ *
+ * The Wizard root carries no `evaluation` prop: under the evidence rule
+ * (CONTRIBUTING §2.3) a dimension only appears on a component if a runtime
+ * dispatches on it. The Wizard root renders a transparent `<section>` —
+ * no color tokens are read here — so adding `evaluation` would reserve API
+ * surface for a speculative future consumer. Re-introduce it the day a
+ * real consumer (e.g. wizard frame chrome) needs it.
+ *
+ * The composite owns its layout; the root does not accept `style` or
+ * `className`. Pass them on a wrapping element instead. See CONTRIBUTING
+ * §4.
+ */
+interface WizardProps {
+  /**
+   * Controlled current step index (0-based). When the user has advanced
+   * past the last step, `currentStep === numberOfSteps` — this is the
+   * terminal state that renders the {@link WizardSummary} sub-part (if
+   * provided). Pair with {@link WizardProps.onStepChange}.
+   */
+  currentStep?: number;
+  /**
+   * Initial step index when rendering uncontrolled.
+   * @default 0
+   */
+  defaultStep?: number;
+  /**
+   * Fires whenever the active step changes — controlled or uncontrolled.
+   */
+  onStepChange?: (step: number) => void;
+  /**
+   * Accessible name for the wizard region (rendered as `aria-label`).
+   * Always provide one (or `aria-labelledby`) — the wizard renders a
+   * `<section>` landmark and screen-reader users navigate by its name.
+   */
+  'aria-label'?: string;
+  /**
+   * Builds the text announced by the wizard's visually-hidden
+   * `aria-live=polite` region whenever the active step changes.
+   * The default is an English fallback (`"Step 2 of 3"` / `"Complete"`) —
+   * localized hosts supply their own copy here (CONTRIBUTING §6).
+   */
+  announceStep?: (state: {
+    currentStep: number;
+    totalSteps: number;
+    isComplete: boolean;
+  }) => string;
+  /**
+   * Expected children: any number of {@link WizardStep} (in order), an
+   * optional {@link WizardSummary}, and an optional {@link WizardNavigation}.
+   * Children are dispatched on their fixed `composition` identity.
+   */
+  children?: React.ReactNode;
+}
+/**
+ * A step-at-a-time Structure composite. The host reads each child's
+ * fixed `composition` identity at runtime to decide which single step
+ * to render, whether to swap in the summary view, and whether to render
+ * the navigation row. This is the canonical evidence that FSL
+ * `Composition` drives behavior from *fixed-identity sub-parts*
+ * (complementing `DialogActions`, which drives behavior from *runtime
+ * values on leaves*).
+ *
+ * @example
+ * ```tsx
+ * const [step, setStep] = React.useState(0);
+ * return (
+ *   <Wizard currentStep={step} onStepChange={setStep} aria-label="Onboarding">
+ *     <WizardStep>First step content</WizardStep>
+ *     <WizardStep>Second step content</WizardStep>
+ *     <WizardStep>Third step content</WizardStep>
+ *     <WizardSummary>All done!</WizardSummary>
+ *     <WizardNavigation prevLabel="Back" nextLabel="Next" finishLabel="Finish" />
+ *   </Wizard>
+ * );
+ * ```
+ */
+declare const Wizard: {
+  ({
+    currentStep,
+    defaultStep,
+    onStepChange,
+    announceStep,
+    children,
+    ...props
+  }: WizardProps): import("react/jsx-runtime").JSX.Element;
+  displayName: "Wizard";
+};
+/**
+ * Formal semantic identity — a step body inside a {@link Wizard}.
+ */
+declare const wizardStepMeta: {
+  readonly displayName: "WizardStep";
+  readonly entity: "Structure";
+  readonly structure: "content";
+  readonly composition: "step";
+};
+/**
+ * Props for {@link WizardStep}.
+ */
+interface WizardStepProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'style' | 'className'> {
+  /**
+   * Optional accessible label for this step (rendered as `aria-label`).
+   */
+  'aria-label'?: string;
+  /** Step body — freeform content (fields, descriptions, media). */
+  children?: React.ReactNode;
+}
+declare const WizardStep: WizardSlotComponent<WizardStepProps, "step">;
+/**
+ * Formal semantic identity — summary view shown after the last step.
+ */
+declare const wizardSummaryMeta: {
+  readonly displayName: "WizardSummary";
+  readonly entity: "Structure";
+  readonly structure: "content";
+  readonly composition: "summary";
+};
+/**
+ * Props for {@link WizardSummary}.
+ */
+type WizardSummaryProps = Omit<React.HTMLAttributes<HTMLDivElement>, 'style' | 'className'>;
+declare const WizardSummary: WizardSlotComponent<WizardSummaryProps, "summary">;
+/**
+ * Formal semantic identity — the navigation slot inside a {@link Wizard}.
+ */
+declare const wizardNavigationMeta: {
+  readonly displayName: "WizardNavigation";
+  readonly entity: "Structure";
+  readonly structure: "actions";
+  readonly composition: "navigation";
+};
+interface WizardNavigationCommonProps {
+  /**
+   * Fires when the user advances past the last step (first click of
+   * `Finish`). The Wizard host transitions to the `isComplete` state
+   * and renders the {@link WizardSummary} if one is provided.
+   */
+  onFinish?: () => void;
+}
+interface WizardNavigationLabelProps extends WizardNavigationCommonProps {
+  /**
+   * Label for the "previous step" button. **Required** — flow-critical
+   * labels have no English default (CONTRIBUTING §6 / ADR-001); the
+   * caller supplies localized copy.
+   */
+  prevLabel: React.ReactNode;
+  /** Label for the "next step" button. **Required** — see `prevLabel`. */
+  nextLabel: React.ReactNode;
+  /** Label for the final-step button. **Required** — see `prevLabel`. */
+  finishLabel: React.ReactNode;
+  children?: never;
+}
+interface WizardNavigationRenderProps extends WizardNavigationCommonProps {
+  /**
+   * Replace the default button row with a render-prop so the host can
+   * compose custom controls while still reading wizard state from the
+   * same context (validation gating, async next, etc.). When provided,
+   * the label props do not apply — the render-prop owns all copy.
+   */
+  children: (state: WizardState) => React.ReactNode;
+  prevLabel?: never;
+  nextLabel?: never;
+  finishLabel?: never;
+}
+/**
+ * Props for {@link WizardNavigation} — either the default row with
+ * caller-supplied labels, or a render-prop that owns the whole row.
+ */
+type WizardNavigationProps = WizardNavigationLabelProps | WizardNavigationRenderProps;
+declare const WizardNavigation: WizardSlotComponent<WizardNavigationProps, "navigation">;
+//#endregion
+export { Wizard, WizardNavigation, WizardNavigationProps, WizardProps, WizardStep, WizardStepProps, WizardSummary, WizardSummaryProps, wizardMeta, wizardNavigationMeta, wizardStepMeta, wizardSummaryMeta };

package/dist/composites/Wizard/Wizard.mjs

@@ -0,0 +1,324 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+import { Button } from "../../components/Button/Button.mjs";
+import { createCompositeScope } from "../scope.mjs";
+import { vars } from "@ttoss/fsl-theme/vars";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import * as React from "react";
+
+//#region src/composites/Wizard/Wizard.tsx
+/**
+* Tag a component as a Wizard slot. Returns the same component augmented
+* with a typed `.composition` literal — no cast, no post-declaration
+* mutation in the caller.
+*/
+var defineWizardSlot = (Component, composition) => {
+  return Object.assign(Component, {
+    composition
+  });
+};
+var REACT_MEMO_TYPE = Symbol.for("react.memo");
+var REACT_FORWARD_REF_TYPE = Symbol.for("react.forward_ref");
+var readComposition = type => {
+  if (type === null || typeof type !== "object" && typeof type !== "function") return;
+  const candidate = type.composition;
+  if (candidate === "step" || candidate === "summary" || candidate === "navigation") return candidate;
+};
+var getChildComposition = child => {
+  if (!React.isValidElement(child)) return void 0;
+  let type = child.type;
+  for (let depth = 0; depth < 8; depth++) {
+    const direct = readComposition(type);
+    if (direct !== void 0) return direct;
+    if (typeof type !== "object" || type === null) return void 0;
+    const wrapped = type;
+    if (wrapped.$$typeof === REACT_MEMO_TYPE) {
+      type = wrapped.type;
+      continue;
+    }
+    if (wrapped.$$typeof === REACT_FORWARD_REF_TYPE) {
+      type = wrapped.render;
+      continue;
+    }
+    return;
+  }
+};
+var wizardScope = createCompositeScope("Wizard");
+var VISUALLY_HIDDEN_STYLE = {
+  position: "absolute",
+  width: "1px",
+  height: "1px",
+  padding: 0,
+  margin: "-1px",
+  overflow: "hidden",
+  clipPath: "inset(50%)",
+  whiteSpace: "nowrap",
+  border: 0
+};
+/**
+* Default step announcement — an English fallback, documented per the
+* package i18n rule (CONTRIBUTING §6 / ADR-001): supplementary AT feedback
+* may ship a default; localized hosts override via
+* {@link WizardProps.announceStep}.
+*/
+var defaultAnnounceStep = ({
+  currentStep,
+  totalSteps,
+  isComplete
+}) => {
+  if (isComplete) return "Complete";
+  return `Step ${currentStep + 1} of ${totalSteps}`;
+};
+/**
+* Formal semantic identity — Wizard root (Structure entity, root part).
+*/
+var wizardMeta = {
+  displayName: "Wizard",
+  entity: "Structure",
+  structure: "root"
+};
+/**
+* A step-at-a-time Structure composite. The host reads each child's
+* fixed `composition` identity at runtime to decide which single step
+* to render, whether to swap in the summary view, and whether to render
+* the navigation row. This is the canonical evidence that FSL
+* `Composition` drives behavior from *fixed-identity sub-parts*
+* (complementing `DialogActions`, which drives behavior from *runtime
+* values on leaves*).
+*
+* @example
+* ```tsx
+* const [step, setStep] = React.useState(0);
+* return (
+*   <Wizard currentStep={step} onStepChange={setStep} aria-label="Onboarding">
+*     <WizardStep>First step content</WizardStep>
+*     <WizardStep>Second step content</WizardStep>
+*     <WizardStep>Third step content</WizardStep>
+*     <WizardSummary>All done!</WizardSummary>
+*     <WizardNavigation prevLabel="Back" nextLabel="Next" finishLabel="Finish" />
+*   </Wizard>
+* );
+* ```
+*/
+var Wizard = ({
+  currentStep,
+  defaultStep = 0,
+  onStepChange,
+  announceStep = defaultAnnounceStep,
+  children,
+  ...props
+}) => {
+  const [internalStep, setInternalStep] = React.useState(defaultStep);
+  const step = currentStep ?? internalStep;
+  const rootRef = React.useRef(null);
+  const setStep = React.useCallback(next => {
+    if (currentStep === void 0) setInternalStep(next);
+    onStepChange?.(next);
+  }, [currentStep, onStepChange]);
+  const classified = React.useMemo(() => {
+    const steps = [];
+    let summary = null;
+    let navigation = null;
+    const unknown = [];
+    React.Children.forEach(children, child => {
+      const composition = getChildComposition(child);
+      if (composition === "step" && React.isValidElement(child)) steps.push(child);else if (composition === "summary" && React.isValidElement(child)) summary = child;else if (composition === "navigation" && React.isValidElement(child)) navigation = child;else unknown.push(child);
+    });
+    return {
+      steps,
+      summary,
+      navigation,
+      unknown
+    };
+  }, [children]);
+  const totalSteps = classified.steps.length;
+  const safeStep = Math.max(0, Math.min(step, totalSteps));
+  const isComplete = safeStep >= totalSteps && totalSteps > 0;
+  const goTo = React.useCallback(next => {
+    setStep(Math.max(0, Math.min(next, totalSteps)));
+  }, [setStep, totalSteps]);
+  const goNext = React.useCallback(() => {
+    return goTo(safeStep + 1);
+  }, [goTo, safeStep]);
+  const goPrev = React.useCallback(() => {
+    return goTo(safeStep - 1);
+  }, [goTo, safeStep]);
+  const contextValue = React.useMemo(() => {
+    return {
+      currentStep: safeStep,
+      totalSteps,
+      isFirst: safeStep === 0,
+      isLast: totalSteps > 0 && safeStep === totalSteps - 1,
+      isComplete,
+      goNext,
+      goPrev,
+      goTo
+    };
+  }, [safeStep, totalSteps, isComplete, goNext, goPrev, goTo]);
+  const activeStep = isComplete ? classified.summary : classified.steps[safeStep] ?? null;
+  const prevStepRef = React.useRef(safeStep);
+  React.useEffect(() => {
+    if (prevStepRef.current === safeStep) return;
+    prevStepRef.current = safeStep;
+    rootRef.current?.querySelector("[data-part=\"content\"]")?.focus();
+  }, [safeStep]);
+  return /* @__PURE__ */jsx(wizardScope.Provider, {
+    value: contextValue,
+    children: /* @__PURE__ */jsxs("section", {
+      ...props,
+      ref: rootRef,
+      "data-scope": "wizard",
+      "data-part": "root",
+      "data-current-step": safeStep,
+      "data-total-steps": totalSteps,
+      "data-complete": isComplete ? "true" : void 0,
+      style: {
+        boxSizing: "border-box",
+        display: "flex",
+        flexDirection: "column",
+        gap: vars.spacing.gap.stack.md,
+        ...vars.text.body.md
+      },
+      children: [/* @__PURE__ */jsx("div", {
+        "data-scope": "wizard",
+        "data-part": "status",
+        "aria-live": "polite",
+        style: VISUALLY_HIDDEN_STYLE,
+        children: totalSteps > 0 ? announceStep({
+          currentStep: safeStep,
+          totalSteps,
+          isComplete
+        }) : null
+      }), activeStep, classified.navigation, classified.unknown]
+    })
+  });
+};
+Wizard.displayName = wizardMeta.displayName;
+/**
+* Formal semantic identity — a step body inside a {@link Wizard}.
+*/
+var wizardStepMeta = {
+  displayName: "WizardStep",
+  entity: "Structure",
+  structure: "content",
+  composition: "step"
+};
+/**
+* A single step's body inside a Wizard. Only the step at the current
+* index is rendered — selection is the Wizard host's runtime dispatch
+* on this component's fixed `composition` identity.
+*/
+var WizardStepBase = props => {
+  wizardScope.use(wizardStepMeta.displayName);
+  return /* @__PURE__ */jsx("div", {
+    tabIndex: -1,
+    ...props,
+    "data-scope": "wizard",
+    "data-part": "content",
+    "data-composition": "step",
+    style: {
+      boxSizing: "border-box",
+      display: "flex",
+      flexDirection: "column",
+      gap: vars.spacing.gap.stack.sm
+    }
+  });
+};
+WizardStepBase.displayName = wizardStepMeta.displayName;
+var WizardStep = defineWizardSlot(WizardStepBase, "step");
+/**
+* Formal semantic identity — summary view shown after the last step.
+*/
+var wizardSummaryMeta = {
+  displayName: "WizardSummary",
+  entity: "Structure",
+  structure: "content",
+  composition: "summary"
+};
+/**
+* A summary view shown once the user has advanced past the last
+* {@link WizardStep}. Selection is the Wizard host's runtime dispatch on
+* this component's fixed `composition` identity — rendered if and only if
+* `currentStep === totalSteps`.
+*/
+var WizardSummaryBase = props => {
+  wizardScope.use(wizardSummaryMeta.displayName);
+  return /* @__PURE__ */jsx("div", {
+    tabIndex: -1,
+    ...props,
+    "data-scope": "wizard",
+    "data-part": "content",
+    "data-composition": "summary",
+    style: {
+      boxSizing: "border-box",
+      display: "flex",
+      flexDirection: "column",
+      gap: vars.spacing.gap.stack.sm
+    }
+  });
+};
+WizardSummaryBase.displayName = wizardSummaryMeta.displayName;
+var WizardSummary = defineWizardSlot(WizardSummaryBase, "summary");
+/**
+* Formal semantic identity — the navigation slot inside a {@link Wizard}.
+*/
+var wizardNavigationMeta = {
+  displayName: "WizardNavigation",
+  entity: "Structure",
+  structure: "actions",
+  composition: "navigation"
+};
+/**
+* Default navigation row for a {@link Wizard}. Reads wizard state from
+* React context — rendering is otherwise deterministic: `Back` is
+* disabled on the first step; the primary button switches label from
+* the next label to the finish label on the last step and fires
+* `onFinish` before advancing. All labels are caller-supplied — the
+* package ships no user-facing copy (CONTRIBUTING §6 / ADR-001).
+*/
+var WizardNavigationBase = ({
+  prevLabel,
+  nextLabel,
+  finishLabel,
+  onFinish,
+  children
+}) => {
+  const ctx = wizardScope.use(wizardNavigationMeta.displayName);
+  const content = children ? children(ctx) : /* @__PURE__ */jsxs(Fragment, {
+    children: [/* @__PURE__ */jsx(Button, {
+      evaluation: "muted",
+      onPress: ctx.goPrev,
+      isDisabled: ctx.isFirst || ctx.isComplete,
+      children: prevLabel
+    }), /* @__PURE__ */jsx(Button, {
+      evaluation: "primary",
+      composition: "primaryAction",
+      consequence: ctx.isLast ? "committing" : "neutral",
+      isDisabled: ctx.isComplete,
+      onPress: () => {
+        if (ctx.isLast) onFinish?.();
+        ctx.goNext();
+      },
+      children: ctx.isLast ? finishLabel : nextLabel
+    })]
+  });
+  return /* @__PURE__ */jsx("div", {
+    "data-scope": "wizard",
+    "data-part": "actions",
+    "data-composition": "navigation",
+    style: {
+      boxSizing: "border-box",
+      display: "flex",
+      flexDirection: "row",
+      alignItems: "center",
+      justifyContent: "flex-end",
+      gap: vars.spacing.gap.inline.md,
+      marginBlockStart: vars.spacing.gap.stack.sm
+    },
+    children: content
+  });
+};
+WizardNavigationBase.displayName = wizardNavigationMeta.displayName;
+var WizardNavigation = defineWizardSlot(WizardNavigationBase, "navigation");
+
+//#endregion
+export { Wizard, WizardNavigation, WizardStep, WizardSummary, wizardMeta, wizardNavigationMeta, wizardStepMeta, wizardSummaryMeta };

package/dist/composites/scope.cjs

@@ -0,0 +1,124 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+const require_runtime = require('../_virtual/_rolldown/runtime.cjs');
+let react = require("react");
+react = require_runtime.__toESM(react, 1);
+
+//#region src/composites/scope.ts
+/**
+* Composite Scope — runtime host-presence guard.
+*
+* The Component Semantics Projection treats Composition as a flat vocabulary
+* (see `docs/.../component-model.md` §"Parent disambiguation"): a slot role
+* like `'heading'` is legal on its declared Entity regardless of which host
+* renders it. The data model intentionally has no `host` field, and the FSL
+* Structural Language §10 lists no Host × Role legality matrix.
+*
+* What is *not* covered by that flatness is the runtime invariant that some
+* sub-parts only make sense inside their host (e.g. `<DialogHeading>` solto
+* is not a meaningful element). This module closes that gap with two tiny
+* builders — chosen by *name*, not by a `<true>` type sentinel — so the
+* author's intent is self-evident at the call site:
+*
+*   1. `createPresenceScope(host)` — pure host-presence guard. No state is
+*      shared; sub-parts only need to assert "I am inside <Host>". Provider
+*      takes no `value` prop. Used by Dialog, Form, TextField, Menu.
+*
+*   2. `createCompositeScope<T>(host)` — host shares typed state with its
+*      sub-parts (evaluation, controlled step, validation, …). Provider
+*      requires a `value` of type `T`. Used by Accordion, Wizard.
+*
+* Both builders share the same error contract: `use('<SubPart>')` outside
+* the host throws an `Error` whose message names both the sub-part and the
+* expected host. Both set `Context.displayName = '<Host>Scope'` for nice
+* DevTools output.
+*
+* Authoring rule (mirrored in CONTRIBUTING §2.3): if the host has no value
+* to share with sub-parts, use `createPresenceScope`. If TypeScript tempts
+* you to write `createCompositeScope<true>('X')`, you wanted
+* `createPresenceScope('X')`.
+*
+* @example Presence guard
+* ```tsx
+* const formScope = createPresenceScope('Form');
+*
+* export const Form = ({ children }) => (
+*   <formScope.Provider>{children}</formScope.Provider>
+* );
+*
+* export const FormSubmit = (props) => {
+*   formScope.use('FormSubmit');
+*   return <button type="submit" {...props} />;
+* };
+* ```
+*
+* @example Stateful scope
+* ```tsx
+* const wizardScope = createCompositeScope<WizardContextValue>('Wizard');
+*
+* export const Wizard = ({ children }) => {
+*   const ctx = useWizardState(...);
+*   return <wizardScope.Provider value={ctx}>{children}</wizardScope.Provider>;
+* };
+*
+* export const WizardNavigation = () => {
+*   const ctx = wizardScope.use('WizardNavigation');
+*   return <button onClick={ctx.goNext}>Next</button>;
+* };
+* ```
+*/
+var PRESENT = Symbol("composite-scope.present");
+/** Throws the canonical out-of-host error for a sub-part. */
+var throwOutOfHost = (consumerDisplayName, hostDisplayName) => {
+  throw new Error(`<${consumerDisplayName}> must be rendered inside <${hostDisplayName}>.`);
+};
+/**
+* Creates a scope where the host shares typed state with its sub-parts.
+*
+* @param hostDisplayName - Display name of the host component, used in the
+*   error message thrown by `use()` when a sub-part is rendered outside.
+*   Must match the host's `*Meta.displayName`.
+*/
+var createCompositeScope = hostDisplayName => {
+  const Context = react.createContext(null);
+  Context.displayName = `${hostDisplayName}Scope`;
+  return {
+    Provider: Context.Provider,
+    use: consumerDisplayName => {
+      const value = react.useContext(Context);
+      if (value === null) return throwOutOfHost(consumerDisplayName, hostDisplayName);
+      return value;
+    }
+  };
+};
+/**
+* Creates a presence-only scope. Sub-parts use `scope.use('<Name>')` to
+* assert they are rendered inside `<Host>` — no value is shared.
+*
+* Use this when the host has nothing to publish to sub-parts. If you find
+* yourself reaching for `createCompositeScope<true>('X')`, use this
+* instead — it is the same contract with a clearer name and zero
+* boilerplate at the call site (`<Provider>` instead of
+* `<Provider value={true}>`).
+*/
+var createPresenceScope = hostDisplayName => {
+  const Context = react.createContext(null);
+  Context.displayName = `${hostDisplayName}Scope`;
+  const Provider = ({
+    children
+  }) => {
+    return react.createElement(Context.Provider, {
+      value: PRESENT
+    }, children);
+  };
+  Provider.displayName = `${hostDisplayName}ScopeProvider`;
+  return {
+    Provider,
+    use: consumerDisplayName => {
+      if (react.useContext(Context) !== PRESENT) throwOutOfHost(consumerDisplayName, hostDisplayName);
+    }
+  };
+};
+
+//#endregion
+exports.createCompositeScope = createCompositeScope;
+exports.createPresenceScope = createPresenceScope;