@reddb-io/ui-kit 0.3.4 → 0.3.5

package/vendor/ds/kits/app/src/core/contracts/storenavigation.ts

@@ -0,0 +1,20 @@
+import type { NavbarCollapse } from "@reddb-io/design-system/base";
+import type { ApplicationNavigationItem } from "../../composites/navigation.behavior";
+
+/** Portable StoreNavigation properties shared by native adapters. */
+export interface StoreNavigationContract {
+/** Accessible name for the navbar's `nav` landmark. */
+    label: string;
+/** Destinations, one link per entry in the given order; each `id` must be unique. */
+    items: readonly ApplicationNavigationItem[];
+/**
+     * The `id` of the item for the current page. It must match exactly one entry in `items`, or the
+     * component throws.
+     */
+    currentId: string;
+/**
+     * How the links fold into a menu: `responsive` (by the navbar's own width), `expanded` or
+     * `collapsed`. Defaults to `responsive`.
+     */
+    collapse?: NavbarCollapse;
+}

package/vendor/ds/kits/app/src/core/contracts/taskcard.ts

@@ -0,0 +1,7 @@
+import type { TaskListItem } from "../../composites/task-list.behavior";
+export interface TaskCardContract {
+  /** Caller-owned task lifecycle and progress, shared with TaskList. */
+  item: TaskListItem;
+  /** Draw the enclosing surface; false embeds the same task content in a list. */
+  surface?: boolean;
+}

package/vendor/ds/kits/app/src/core/contracts/tasklist.ts

@@ -0,0 +1,13 @@
+import type { TaskListItem } from "../../composites/task-list.behavior";
+
+/** Portable TaskList properties shared by native adapters. */
+export interface TaskListContract {
+/** Accessible name of the task list. */
+    label: string;
+/** Caller-owned tasks, in display order, with unique stable ids. */
+    items: readonly TaskListItem[];
+/** Title of the default empty state. Defaults to No tasks. */
+    emptyLabel?: string;
+/** Explanation for the default empty state. */
+    emptyDescription?: string;
+}

package/vendor/ds/kits/app/src/core/contracts/telemetryrow.ts

@@ -0,0 +1,17 @@
+import type { Tone } from "@reddb-io/design-system/base";
+export interface TelemetryRowContract {
+  /** Name of the entity or resource. */
+  label: string;
+  /** Bounded resource reading; distinct from the operational state. */
+  value: number;
+  /** Resource capacity. */
+  max?: number;
+  /** Explicit operational status. */
+  stateLabel?: string;
+  /** Independent condition such as locked, equipped or maintenance. */
+  condition?: string;
+  /** Supporting context or unit. */
+  description?: string;
+  /** Meaning of the operational status. */
+  tone?: Tone;
+}

package/vendor/ds/kits/app/src/core/contracts/toolbar.ts

@@ -0,0 +1,25 @@
+import type { ToolbarItem } from "../../composites/command-surfaces.behavior";
+import type { ToolbarSize } from "../../composites/toolbar.variants";
+type Orientation = "horizontal" | "vertical";
+/** Portable Toolbar properties shared by native adapters. */
+export interface ToolbarContract {
+/** Accessible name for the toolbar. */
+    label: string;
+/**
+     * Actions and destinations in order; an enabled item with an `href` renders as a link, any
+     * other as a button that calls its `onselect`.
+     */
+    items?: readonly ToolbarItem[];
+/**
+     * Layout direction and the arrow-key axis: `horizontal` or `vertical`. Defaults to
+     * `horizontal`.
+     */
+    orientation?: Orientation;
+/** Size of the item controls: `sm`, `md` or `lg`. Defaults to `md`. */
+    size?: ToolbarSize;
+/**
+     * Whether arrow-key focus wraps from the last item back to the first, and the reverse. Defaults
+     * to `true`.
+     */
+    loop?: boolean;
+}

package/vendor/ds/kits/app/src/core/diff.ts

@@ -0,0 +1,7 @@
+/** One aligned comparison row. The consumer owns diff computation. */
+  export interface DiffRow {
+    /** The line before the change; omit it for a pure addition. */
+    before?: string;
+    /** The line after the change; omit it for a pure removal. */
+    after?: string;
+  }

package/vendor/ds/kits/app/src/core/entity-inspector.ts

@@ -0,0 +1,26 @@
+export interface InspectorEntity {
+  /** Stable application-owned identity. */
+  id: string;
+  /** Visible entity title. */
+  label: string;
+  /** Supporting context beneath the title. */
+  description?: string;
+}
+export function inspectedEntity(
+  items: readonly InspectorEntity[],
+  selected: string | null,
+) {
+  const ids = new Set<string>();
+  for (const item of items) {
+    if (!item.id || ids.has(item.id))
+      throw new Error("EntityInspector: ids must be non-empty and unique.");
+    ids.add(item.id);
+  }
+  const index = items.findIndex((item) => item.id === selected);
+  return {
+    entity: items[index],
+    index,
+    previous: items[index - 1]?.id,
+    next: index < 0 ? undefined : items[index + 1]?.id,
+  };
+}

package/vendor/ds/kits/app/src/core/entity-journey.ts

@@ -0,0 +1,52 @@
+import type { Tone } from "@reddb-io/design-system/base";
+/** Caller-observed execution state; selection never advances the journey. */
+export type JourneyState =
+  | "complete"
+  | "current"
+  | "upcoming"
+  | "blocked"
+  | "failed"
+  | "skipped";
+export interface JourneyStage {
+  /** Stable identity shared with an inspector or scene. */
+  id: string;
+  /** Visible stage name. */
+  label: string;
+  /** Explicit observed state, never inferred from position or elapsed time. */
+  state: JourneyState;
+  /** Optional supporting observation. */
+  description?: string;
+  /** Caller-formatted elapsed duration or timestamp. */
+  elapsed?: string;
+  /** Localized state label; omitted, uses the English state name. */
+  stateLabel?: string;
+}
+const states = {
+  complete: "Completed",
+  current: "In progress",
+  upcoming: "Upcoming",
+  blocked: "Blocked",
+  failed: "Failed",
+  skipped: "Skipped",
+};
+export function journeyStages(items: readonly JourneyStage[]) {
+  const ids = new Set<string>();
+  return items.map((item) => {
+    if (!item.id.trim() || ids.has(item.id))
+      throw new Error("EntityJourney: stage ids must be nonempty and unique");
+    if (!Object.hasOwn(states, item.state))
+      throw new Error("EntityJourney: invalid observed state");
+    ids.add(item.id);
+    const tone: Tone =
+      item.state === "failed"
+        ? "danger"
+        : item.state === "blocked"
+          ? "warning"
+          : item.state === "current"
+            ? "info"
+            : item.state === "complete"
+              ? "success"
+              : "neutral";
+    return { ...item, tone, stateLabel: item.stateLabel ?? states[item.state] };
+  });
+}

package/vendor/ds/kits/app/src/core/measure.ts

@@ -0,0 +1,7 @@
+/** Measure real chrome geometry and keep it synchronized without owning a rendering framework. */
+export function observeElementSize(element: HTMLElement | null | undefined, changed: (rect: DOMRectReadOnly) => void): () => void {
+  if (!element) return () => {};
+  const measure = () => changed(element.getBoundingClientRect()); measure();
+  if (typeof ResizeObserver === "undefined") return () => {};
+  const observer = new ResizeObserver(measure); observer.observe(element); return () => observer.disconnect();
+}

package/vendor/ds/kits/app/src/core/operational.ts

@@ -0,0 +1,42 @@
+import type { Tone } from "@reddb-io/design-system/base";
+export interface PropertyItem {
+  /** Stable name of the property. */ label: string;
+  /** Caller-formatted reading, never an editor. */ value: string | number;
+}
+export interface PhaseGate {
+  /** Stable identity. */ id: string;
+  /** Visible gate name. */ label: string;
+  /** Explicit state; completion is not inferred from work progress. */ state:
+    "pending" | "running" | "passed" | "failed";
+  /** Optional context or approval requirement. */ description?: string;
+}
+export const GATE_LABELS = {
+  pending: "Pending",
+  running: "Running",
+  passed: "Passed",
+  failed: "Failed",
+} as const;
+export const GATE_TONES: Record<PhaseGate["state"], Tone> = {
+  pending: "neutral",
+  running: "info",
+  passed: "success",
+  failed: "danger",
+};
+export function validateGates(gates: readonly PhaseGate[]) {
+  const ids = new Set<string>();
+  for (const gate of gates) {
+    if (!gate.id || ids.has(gate.id) || !Object.hasOwn(GATE_LABELS, gate.state))
+      throw new Error(
+        "PhaseSummary: gates require unique ids and known states",
+      );
+    ids.add(gate.id);
+  }
+  return gates;
+}
+
+export const PLAYBACK_SPEEDS = [
+  { value: "0.5", label: "0.5×" },
+  { value: "1", label: "1×" },
+  { value: "2", label: "2×" },
+  { value: "4", label: "4×" },
+] as const;

package/vendor/ds/kits/app/src/core/product-list.ts

@@ -0,0 +1,16 @@
+
+/** Caller-owned content for one entry in the canonical product collection. */
+export interface ProductListItem<Content = unknown> {
+  /** Stable identity used by the keyed collection. */
+  id: string;
+  /** Visible product name and the accessible name of its optional link. */
+  name: string;
+  /** Optional canonical product destination. */
+  href?: string;
+  description?: string;
+  price?: string;
+  /** Caller-owned product imagery, including its own alternative text. */
+  media?: Content;
+  /** Caller-owned canonical controls, kept after the product identity. */
+  actions?: Content;
+}

package/vendor/ds/kits/app/src/core/settings-row.ts

@@ -0,0 +1,9 @@
+import { fieldAssociation, type FieldControlProps } from "@reddb-io/design-system/base/recipes";
+import type { SettingsRowContract } from "./contracts/settingsrow";
+
+/** The setting name and description belong to fields; actions receive no naming overrides. */
+export function settingsRowAssociation(props: SettingsRowContract & { id: string }) {
+  const association = fieldAssociation({ id: props.id, help: props.description, error: props.error, required: props.required });
+  return { ...association, labelId: `${props.id}-label` };
+}
+export type { FieldControlProps };

package/vendor/ds/kits/app/src/core/shopping-cart.ts

@@ -0,0 +1,17 @@
+/** Caller-owned product data used by one editable cart row. */
+export interface ShoppingCartItem<Content = unknown> {
+  id: string;
+  name: string;
+  description?: string;
+  price: string;
+  quantity: number;
+  quantityName?: string;
+  disabled?: boolean;
+  /** Caller-owned product media with its own accessible alternative. */
+  media?: Content;
+  /** Caller-owned detail rendering for configurations or other product metadata. */
+  details?: Content;
+  /** Caller-owned per-item actions rendered after the canonical quantity control. */
+  actions?: Content;
+}
+

package/vendor/ds/kits/app/src/core/sidebar-rail.ts

@@ -0,0 +1,58 @@
+import type { IconGlyph } from "@reddb-io/design-system/base";
+  import { navigationBadge, type NavigationMarkers } from "../composites/navigation.behavior";
+
+  export interface SidebarRailItem extends NavigationMarkers {
+    /** Stable identity emitted when this item is chosen. */
+    id: string;
+    /**
+     * Accessible name and Tooltip content for the visually compact control. A tile that shows
+     * initials in icon-only mode is named `<initials>, <label>` unless `label` already holds them as words, so its
+     * name starts with what it shows (WCAG 2.5.3).
+     */
+    label: string;
+    /** Native destination; omit for an action or contextual section menu. */
+    href?: string;
+    /** Optional glyph rendered only through the Base Icon contract. */
+    icon?: IconGlyph;
+    /**
+     * Initials or a short affordance such as "+" when no glyph is supplied; defaults to the first
+     * two letters of `label`, upper-cased.
+     */
+    fallback?: string;
+    /** Present but unavailable and omitted from the rail's roving focus order. */
+    disabled?: boolean;
+    /** Disclosure state when the selected rail item toggles an adjacent panel. */
+    expanded?: boolean;
+    /** Id of the adjacent panel controlled by this disclosure item. */
+    controls?: string;
+    /** Draw a horizontal divider before this destination to separate groups in the vertical rail. It adds no focus stop. */
+    separatorBefore?: boolean;
+  }
+
+  /** The text a glyph-less tile shows: its `fallback`, else the label's first two letters. */
+  export function face(item: SidebarRailItem): string {
+    return item.fallback ?? item.label.slice(0, 2).toUpperCase();
+  }
+
+  const words = (text: string): string[] =>
+    text.normalize("NFKD").toLowerCase().split(/[^\p{L}\p{N}]+/u).filter(Boolean);
+
+  /**
+   * A tile's accessible name. WCAG 2.5.3 (Label in Name): a speech-input user
+   * says what the tile shows, so visible initials lead the name unless the
+   * label already holds them as words. A glyph or a symbol such as "+" shows
+   * no words, and the label alone names it.
+   */
+  export function nameOf(item: SidebarRailItem, labelled = false): string {
+    if (item.icon) return item.label;
+    if (labelled) {
+      // The visible name precedes the face in reading order. Include its
+      // count and initials together before the full notification description.
+      return [item.label, item.badge === undefined ? undefined : navigationBadge(item.badge), face(item)].filter(Boolean).join(", ");
+    }
+    const shown = words(face(item));
+    if (shown.length === 0) return item.label;
+    const named = words(item.label);
+    const held = named.some((_, start) => shown.every((word, offset) => named[start + offset] === word));
+    return held ? item.label : `${face(item)}, ${item.label}`;
+  }

package/vendor/ds/kits/app/src/entity-inspector.variants.ts

@@ -0,0 +1,14 @@
+import { tv } from "tailwind-variants";
+export const entityInspector = tv({
+  slots: {
+    root: "flex min-w-0 flex-col overflow-hidden rounded-[var(--reddb-radius-lg)] border border-muted bg-elevation-raised-surface text-foreground",
+    toolbar:
+      "flex min-w-0 flex-wrap items-center justify-between gap-[var(--reddb-spatial-gap-sm)] border-b border-muted p-[var(--reddb-spatial-inset-sm)]",
+    navigation: "flex flex-wrap items-center gap-[var(--reddb-spatial-gap-sm)]",
+    position: "text-caption tabular-nums text-ink-muted",
+    body: "grid min-w-0 gap-[var(--reddb-spatial-gap-md)] p-[var(--reddb-spatial-inset-md)]",
+    title: "m-0 min-w-0 [overflow-wrap:anywhere] text-heading font-medium",
+    context: "m-0 min-w-0 [overflow-wrap:anywhere] text-caption text-ink-muted",
+    actions: "flex flex-wrap items-center gap-[var(--reddb-spatial-gap-sm)]",
+  },
+});

package/vendor/ds/kits/app/src/entity-journey.variants.ts

@@ -0,0 +1,38 @@
+import { tv } from "tailwind-variants";
+import { typeRoleMerge } from "@reddb-io/design-system/base/recipes";
+export const entityJourney = tv(
+  {
+    slots: {
+      root: "@container/entity-journey min-w-0 text-foreground",
+      list: "m-0 grid min-w-0 list-none grid-cols-1 gap-[var(--reddb-spatial-gap-sm)] p-0 @lg/entity-journey:grid-cols-[repeat(auto-fit,minmax(min(100%,calc(var(--reddb-spatial-control-height-md)*4)),1fr))]",
+      stage:
+        "min-w-0 @lg/entity-journey:row-span-4 @lg/entity-journey:grid @lg/entity-journey:grid-rows-subgrid",
+      item: "flex h-full w-full min-w-0 items-start @lg/entity-journey:row-span-4 @lg/entity-journey:grid @lg/entity-journey:grid-cols-[auto_minmax(0,1fr)] @lg/entity-journey:grid-rows-subgrid gap-[var(--reddb-spatial-gap-sm)] rounded-[var(--reddb-radius-md)] border border-transparent p-[var(--reddb-spatial-inset-sm)] text-start aria-pressed:border-foreground aria-pressed:bg-foreground/10",
+      marker:
+        "flex size-[var(--reddb-spatial-control-height-sm)] shrink-0 items-center justify-center rounded-full border border-control-edge text-caption tabular-nums",
+      body: "grid min-w-0 flex-1 @lg/entity-journey:col-start-2 @lg/entity-journey:row-span-4 @lg/entity-journey:grid-rows-subgrid gap-[var(--reddb-spatial-gap-sm)] [overflow-wrap:anywhere]",
+      label: "text-body font-medium",
+      note: "text-caption text-ink-muted empty:hidden @lg/entity-journey:empty:block",
+      status: "text-caption text-ink-muted",
+      elapsed:
+        "text-caption tabular-nums text-ink-muted empty:hidden @lg/entity-journey:empty:block",
+    },
+    variants: {
+      state: {
+        complete: { marker: "bg-foreground text-background border-foreground" },
+        current: { marker: "border-2 border-foreground font-bold" },
+        upcoming: { marker: "text-ink-muted" },
+        blocked: {
+          marker:
+            "text-feedback-warning-foreground border-feedback-warning-foreground",
+        },
+        failed: {
+          marker:
+            "text-feedback-danger-foreground border-feedback-danger-foreground",
+        },
+        skipped: { marker: "text-ink-muted border-dashed" },
+      },
+    },
+  },
+  typeRoleMerge,
+);