@syscore/ui-library 1.25.0 → 2.0.0-beta-publish-workflow-beta.1

package/client/components/ui/layout.tsx

@@ -0,0 +1,1182 @@
+import * as React from "react";
+import { cn } from "@/lib/utils";
+
+const spacing = (n: number): string => `${n * 0.25}rem`;
+
+const warned = new Set<string>();
+
+/** Dev-only, deduped: flags a value that will not follow design-system changes. */
+function warnOnce(message: string): void {
+  if (process.env.NODE_ENV === "production" || warned.has(message)) return;
+  warned.add(message);
+  console.warn(message);
+}
+
+/** Named space scale from design. Change px on `--space-*` in global.css to update apps. */
+export const SPACE_SCALE = {
+  "3xs": 2,
+  "2xs": 4,
+  xs: 8,
+  sm: 12,
+  md: 16,
+  lg: 20,
+  xl: 24,
+  "2xl": 32,
+  "3xl": 40,
+  "4xl": 48,
+  "5xl": 64,
+  "6xl": 80,
+  "7xl": 96,
+  "8xl": 120,
+} as const;
+
+export type SpaceName = keyof typeof SPACE_SCALE;
+export const SPACE_NAMES = Object.keys(SPACE_SCALE) as SpaceName[];
+export const SPACER_SPACES = Object.values(
+  SPACE_SCALE,
+) as unknown as SpacerSpacePx[];
+type SpacerSpacePx = (typeof SPACE_SCALE)[SpaceName];
+
+const PX_TO_SPACE = Object.fromEntries(
+  SPACE_NAMES.map((name) => [SPACE_SCALE[name], name]),
+) as Record<SpacerSpacePx, SpaceName>;
+
+/**
+ * Named space token. Numbers are legacy 4px units, kept only for migration —
+ * they resolve back to a `--space-*` token so a scale change still reaches apps.
+ */
+export type SpaceInput = SpaceName | number;
+
+function tokenCss(name: SpaceName): string {
+  return `var(--space-${name})`;
+}
+
+/**
+ * Resolves to `var(--space-*)` whenever possible so the scale stays the single
+ * source of truth. Legacy 4px units (`gap={4}`) map back onto the scale; a value
+ * off the scale is a frozen literal and warns in development.
+ */
+function gapCss(value: SpaceInput | undefined): string | undefined {
+  if (value == null) return undefined;
+  if (typeof value === "string") return tokenCss(value);
+  if (value === 0) return "0px";
+  const named = PX_TO_SPACE[(value * 4) as SpacerSpacePx];
+  if (named) return tokenCss(named);
+  warnOnce(
+    `layout: spacing ${value} is off the space scale, so ${spacing(value)} is frozen into this app ` +
+      `and a design-system change will not reach it. Use a named token (gap="md").`,
+  );
+  return spacing(value);
+}
+
+const toCssSize = (v: number | string | undefined) =>
+  v === undefined ? undefined : typeof v === "number" ? `${v}px` : v;
+
+type SizeValue = number | string;
+type StackDirection = "vertical" | "horizontal";
+type StackAlign = "start" | "center" | "end" | "stretch" | "baseline";
+type StackJustify =
+  | "start"
+  | "center"
+  | "end"
+  | "between"
+  | "around"
+  | "evenly";
+type StackWrap = boolean | "wrap" | "nowrap" | "wrap-reverse";
+type GridCols = 1 | 2 | 3 | 4 | 6 | 12;
+
+const isWrapped = (wrap?: StackWrap) => wrap === true || wrap === "wrap";
+
+// ---------------------------------------------------------------------------
+// Stack
+// ---------------------------------------------------------------------------
+
+interface StackProps extends React.HTMLAttributes<HTMLElement> {
+  as?: React.ElementType;
+  direction?: StackDirection;
+  gap?: SpaceInput;
+  align?: StackAlign;
+  justify?: StackJustify;
+  /** Main-axis alias used by Astryx HStack / VStack. */
+  hAlign?: StackJustify | StackAlign;
+  /** Cross-axis alias used by Astryx HStack / VStack. */
+  vAlign?: StackJustify | StackAlign;
+  wrap?: StackWrap;
+  padding?: SpaceInput;
+  width?: SizeValue;
+  height?: SizeValue;
+  maxWidth?: SizeValue;
+  minHeight?: SizeValue;
+  isScrollable?: boolean;
+}
+
+const Stack = React.forwardRef<HTMLElement, StackProps>(
+  (
+    {
+      as: Component = "div",
+      direction = "vertical",
+      gap = "md",
+      align,
+      justify,
+      hAlign,
+      vAlign,
+      wrap = false,
+      padding,
+      width,
+      height,
+      maxWidth,
+      minHeight,
+      isScrollable = false,
+      className,
+      style,
+      ...props
+    },
+    ref,
+  ) => {
+    const resolvedJustify =
+      justify ??
+      (direction === "horizontal"
+        ? (hAlign as StackJustify | undefined)
+        : (vAlign as StackJustify | undefined));
+    const resolvedAlign =
+      align ??
+      (direction === "horizontal"
+        ? (vAlign as StackAlign | undefined)
+        : (hAlign as StackAlign | undefined));
+
+    return (
+      <Component
+        ref={ref}
+        className={cn(
+          "stack",
+          direction === "horizontal" && "stack--horizontal",
+          resolvedAlign && `stack--align-${resolvedAlign}`,
+          resolvedJustify && `stack--justify-${resolvedJustify}`,
+          isWrapped(wrap) && "stack--wrap",
+          wrap === "wrap-reverse" && "stack--wrap-reverse",
+          isScrollable && "stack--scrollable",
+          className,
+        )}
+        style={{
+          gap: gapCss(gap),
+          padding: gapCss(padding),
+          width: toCssSize(width),
+          height: toCssSize(height),
+          maxWidth: toCssSize(maxWidth),
+          minHeight: toCssSize(minHeight),
+          ...style,
+        }}
+        {...props}
+      />
+    );
+  },
+);
+Stack.displayName = "Stack";
+
+// ---------------------------------------------------------------------------
+// HStack / VStack
+// ---------------------------------------------------------------------------
+
+type HStackProps = Omit<StackProps, "direction">;
+type VStackProps = Omit<StackProps, "direction">;
+
+const HStack = React.forwardRef<HTMLElement, HStackProps>((props, ref) => (
+  <Stack ref={ref} direction="horizontal" {...props} />
+));
+HStack.displayName = "HStack";
+
+const VStack = React.forwardRef<HTMLElement, VStackProps>((props, ref) => (
+  <Stack ref={ref} direction="vertical" {...props} />
+));
+VStack.displayName = "VStack";
+
+// ---------------------------------------------------------------------------
+// StackItem
+// ---------------------------------------------------------------------------
+
+type StackItemSize = "static" | "fill";
+
+interface StackItemProps extends React.HTMLAttributes<HTMLElement> {
+  as?: React.ElementType;
+  size?: StackItemSize;
+  alignSelf?: StackAlign;
+  isScrollable?: boolean;
+}
+
+const StackItem = React.forwardRef<HTMLElement, StackItemProps>(
+  (
+    {
+      as: Component = "div",
+      size = "static",
+      alignSelf,
+      isScrollable = false,
+      className,
+      ...props
+    },
+    ref,
+  ) => (
+    <Component
+      ref={ref}
+      className={cn(
+        "stack-item",
+        size === "fill" && "stack-item--fill",
+        alignSelf && `stack-item--align-${alignSelf}`,
+        isScrollable && "stack-item--scrollable",
+        className,
+      )}
+      {...props}
+    />
+  ),
+);
+StackItem.displayName = "StackItem";
+
+// ---------------------------------------------------------------------------
+// Grid
+// ---------------------------------------------------------------------------
+
+type GridColumnsConfig =
+  | GridCols
+  | {
+      minWidth: number;
+      max?: number;
+      repeat?: "fill" | "fit";
+    };
+
+interface GridProps extends React.HTMLAttributes<HTMLElement> {
+  as?: React.ElementType;
+  /** Preferred Astryx name. Number = fixed columns; object = auto-fill by min width. */
+  columns?: GridColumnsConfig;
+  /** @deprecated Use `columns`. */
+  cols?: GridCols;
+  colsSm?: GridCols;
+  colsMd?: GridCols;
+  colsLg?: GridCols;
+  gap?: SpaceInput;
+  rowGap?: SpaceInput;
+  columnGap?: SpaceInput;
+  /** @deprecated Use `columnGap`. */
+  colGap?: number;
+  align?: "start" | "center" | "end" | "stretch";
+  justify?: "start" | "center" | "end" | "stretch";
+  width?: SizeValue;
+  height?: SizeValue;
+  maxWidth?: SizeValue;
+  minHeight?: SizeValue;
+}
+
+const Grid = React.forwardRef<HTMLElement, GridProps>(
+  (
+    {
+      as: Component = "div",
+      columns,
+      cols,
+      colsSm,
+      colsMd,
+      colsLg,
+      gap = "md",
+      rowGap,
+      columnGap,
+      colGap,
+      align,
+      justify,
+      width,
+      height,
+      maxWidth,
+      minHeight,
+      className,
+      style,
+      ...props
+    },
+    ref,
+  ) => {
+    const resolvedColumnGap = columnGap ?? colGap;
+    const isResponsive = columns !== undefined && typeof columns === "object";
+    const fixedCols = typeof columns === "number" ? columns : (cols ?? 1);
+
+    let template: string | undefined;
+    if (isResponsive) {
+      const repeat = columns.repeat ?? "fill";
+      if (columns.max) {
+        template = `repeat(auto-${repeat}, minmax(max(${columns.minWidth}px, calc(100% / ${columns.max})), 1fr))`;
+      } else {
+        template = `repeat(auto-${repeat}, minmax(${columns.minWidth}px, 1fr))`;
+      }
+    }
+
+    return (
+      <Component
+        ref={ref}
+        className={cn(
+          "grid-layout",
+          !isResponsive && `grid-layout--cols-${fixedCols}`,
+          !isResponsive && colsSm && `grid-layout--sm-cols-${colsSm}`,
+          !isResponsive && colsMd && `grid-layout--md-cols-${colsMd}`,
+          !isResponsive && colsLg && `grid-layout--lg-cols-${colsLg}`,
+          align && `grid-layout--align-${align}`,
+          justify && `grid-layout--justify-${justify}`,
+          className,
+        )}
+        style={{
+          gridTemplateColumns: template,
+          gap:
+            rowGap === undefined && resolvedColumnGap === undefined
+              ? gapCss(gap)
+              : undefined,
+          rowGap: gapCss(rowGap),
+          columnGap: gapCss(resolvedColumnGap),
+          width: toCssSize(width),
+          height: toCssSize(height),
+          maxWidth: toCssSize(maxWidth),
+          minHeight: toCssSize(minHeight),
+          ...style,
+        }}
+        {...props}
+      />
+    );
+  },
+);
+Grid.displayName = "Grid";
+
+// ---------------------------------------------------------------------------
+// GridSpan
+// ---------------------------------------------------------------------------
+
+interface GridSpanProps extends React.HTMLAttributes<HTMLElement> {
+  as?: React.ElementType;
+  columns?: number | "full";
+  rows?: number;
+}
+
+const GridSpan = React.forwardRef<HTMLElement, GridSpanProps>(
+  (
+    { as: Component = "div", columns, rows, className, style, ...props },
+    ref,
+  ) => (
+    <Component
+      ref={ref}
+      className={cn("grid-span", className)}
+      style={{
+        gridColumn:
+          columns === "full"
+            ? "1 / -1"
+            : columns != null
+              ? `span ${columns}`
+              : undefined,
+        gridRow: rows != null ? `span ${rows}` : undefined,
+        ...style,
+      }}
+      {...props}
+    />
+  ),
+);
+GridSpan.displayName = "GridSpan";
+
+// ---------------------------------------------------------------------------
+// Columns — asymmetric tracks (compat). Prefer Layout + LayoutPanel or GridSpan.
+// ---------------------------------------------------------------------------
+
+type ColumnsPreset =
+  | "sidebar"
+  | "sidebar-right"
+  | "wide-sidebar"
+  | "narrow-sidebar"
+  | "split"
+  | "1-2"
+  | "2-1"
+  | "1-3"
+  | "3-1";
+
+type ColumnsCollapse = "sm" | "md" | "lg";
+
+interface ColumnsProps extends React.HTMLAttributes<HTMLElement> {
+  as?: React.ElementType;
+  preset?: ColumnsPreset;
+  /** Raw `grid-template-columns`. Overrides `preset`; prefer a preset so the value stays in the design system. */
+  template?: string;
+  gap?: SpaceInput;
+  /** @deprecated Use `columnGap`. */
+  colGap?: SpaceInput;
+  columnGap?: SpaceInput;
+  rowGap?: SpaceInput;
+  collapse?: ColumnsCollapse;
+}
+
+/** Sidebar widths reuse the panel scale so a Columns sidebar and a LayoutPanel match. */
+const ColumnsPresetMap: Record<ColumnsPreset, string> = {
+  sidebar: "var(--layout-panel-width-default) 1fr",
+  "sidebar-right": "1fr var(--layout-panel-width-default)",
+  "wide-sidebar": "var(--layout-panel-width-wide) 1fr",
+  "narrow-sidebar": "var(--layout-panel-width-narrow) 1fr",
+  split: "1fr 1fr",
+  "1-2": "1fr 2fr",
+  "2-1": "2fr 1fr",
+  "1-3": "1fr 3fr",
+  "3-1": "3fr 1fr",
+};
+
+const Columns = React.forwardRef<HTMLElement, ColumnsProps>(
+  (
+    {
+      as: Component = "div",
+      preset = "split",
+      template,
+      gap = "xl",
+      colGap,
+      columnGap,
+      rowGap,
+      collapse,
+      className,
+      style,
+      ...props
+    },
+    ref,
+  ) => {
+    const resolvedColumnGap = columnGap ?? colGap;
+    return (
+      <Component
+        ref={ref}
+        className={cn(
+          "columns-layout",
+          collapse && `columns-layout--collapse-${collapse}`,
+          className,
+        )}
+        style={{
+          gridTemplateColumns: template ?? ColumnsPresetMap[preset],
+          gap:
+            rowGap === undefined && resolvedColumnGap === undefined
+              ? gapCss(gap)
+              : undefined,
+          rowGap: gapCss(rowGap),
+          columnGap: gapCss(resolvedColumnGap),
+          ...style,
+        }}
+        {...props}
+      />
+    );
+  },
+);
+Columns.displayName = "Columns";
+
+// ---------------------------------------------------------------------------
+// Center
+// ---------------------------------------------------------------------------
+
+type CenterAxis = "both" | "horizontal" | "vertical";
+
+interface CenterProps extends React.HTMLAttributes<HTMLElement> {
+  as?: React.ElementType;
+  axis?: CenterAxis;
+  width?: SizeValue;
+  height?: SizeValue;
+  maxWidth?: SizeValue;
+  minHeight?: SizeValue;
+  padding?: SpaceInput;
+  isInline?: boolean;
+}
+
+const Center = React.forwardRef<HTMLElement, CenterProps>(
+  (
+    {
+      as: Component = "div",
+      axis = "both",
+      width,
+      height,
+      maxWidth,
+      minHeight,
+      padding,
+      isInline = false,
+      className,
+      style,
+      ...props
+    },
+    ref,
+  ) => (
+    <Component
+      ref={ref}
+      className={cn(
+        "center",
+        isInline && "center--inline",
+        `center--${axis}`,
+        className,
+      )}
+      style={{
+        width: toCssSize(width),
+        height: toCssSize(height),
+        maxWidth: toCssSize(maxWidth),
+        minHeight: toCssSize(minHeight),
+        padding: gapCss(padding),
+        ...style,
+      }}
+      {...props}
+    />
+  ),
+);
+Center.displayName = "Center";
+
+// ---------------------------------------------------------------------------
+// FormLayout
+// ---------------------------------------------------------------------------
+
+type FormLayoutDirection = "vertical" | "horizontal" | "horizontal-labels";
+
+interface FormLayoutProps extends React.HTMLAttributes<HTMLElement> {
+  as?: React.ElementType;
+  direction?: FormLayoutDirection;
+  gap?: SpaceInput;
+  width?: SizeValue;
+  maxWidth?: SizeValue;
+}
+
+const FormLayout = React.forwardRef<HTMLElement, FormLayoutProps>(
+  (
+    {
+      as: Component = "div",
+      direction = "vertical",
+      gap,
+      width,
+      maxWidth,
+      className,
+      style,
+      ...props
+    },
+    ref,
+  ) => (
+    <Component
+      ref={ref}
+      className={cn(
+        "form-layout",
+        direction === "horizontal" && "form-layout--horizontal",
+        direction === "horizontal-labels" && "form-layout--horizontal-labels",
+        className,
+      )}
+      style={{
+        gap: gapCss(gap),
+        width: toCssSize(width),
+        maxWidth: toCssSize(maxWidth),
+        ...style,
+      }}
+      {...props}
+    />
+  ),
+);
+FormLayout.displayName = "FormLayout";
+
+// ---------------------------------------------------------------------------
+// Section
+// ---------------------------------------------------------------------------
+
+type SectionPadding = "none" | "sm" | "md" | "lg" | "xl";
+
+interface SectionProps extends React.HTMLAttributes<HTMLElement> {
+  as?: React.ElementType;
+  padding?: SectionPadding;
+  maxWidth?: SizeValue;
+}
+
+const Section = React.forwardRef<HTMLElement, SectionProps>(
+  (
+    {
+      as: Component = "section",
+      padding = "lg",
+      maxWidth,
+      className,
+      style,
+      ...props
+    },
+    ref,
+  ) => (
+    <Component
+      ref={ref}
+      className={cn(
+        "section-layout",
+        padding !== "none" && `section-layout--${padding}`,
+        className,
+      )}
+      style={{ maxWidth: toCssSize(maxWidth), ...style }}
+      {...props}
+    />
+  ),
+);
+Section.displayName = "Section";
+
+// ---------------------------------------------------------------------------
+// Layout — page shell (header / start panel / content / end panel / footer)
+// ---------------------------------------------------------------------------
+
+type LayoutHeight = "fill" | "auto";
+type LayoutPanelPlacement = "start" | "end";
+
+/** Panel widths come from `--layout-panel-width-*`, never from app-side px. */
+type LayoutPanelWidth = "narrow" | "default" | "wide";
+/** Content measures come from `--layout-measure-*`, never from app-side px. */
+type LayoutMeasure = "sm" | "md" | "lg" | "full";
+
+/**
+ * Slots deliberately drop `className` and `style`: both let an app freeze a value
+ * the design system can no longer change. Every dimension is a named prop that
+ * resolves to a `--layout-*` variable.
+ */
+type LayoutSlotHTMLProps<T = HTMLElement> = Omit<
+  React.HTMLAttributes<T>,
+  "className" | "style"
+>;
+
+function panelWidthVar(
+  width: LayoutPanelWidth | number | undefined,
+): string | undefined {
+  if (width == null) return undefined;
+  if (typeof width === "number") {
+    warnOnce(
+      `LayoutPanel: width={${width}} freezes ${width}px into this app. ` +
+        `Use width="narrow" | "default" | "wide" so --layout-panel-width-* stays in control.`,
+    );
+    return `${width}px`;
+  }
+  return `var(--layout-panel-width-${width})`;
+}
+
+function measureVar(
+  measure: LayoutMeasure | number | string | undefined,
+): string | undefined {
+  if (measure == null) return undefined;
+  if (
+    typeof measure !== "string" ||
+    !["sm", "md", "lg", "full"].includes(measure)
+  ) {
+    const frozen = toCssSize(measure as number | string);
+    warnOnce(
+      `Layout: contentWidth={${JSON.stringify(measure)}} freezes ${frozen} into this app. ` +
+        `Use contentWidth="sm" | "md" | "lg" | "full" so --layout-measure-* stays in control.`,
+    );
+    return frozen;
+  }
+  return `var(--layout-measure-${measure})`;
+}
+type LayoutSlotId = "header" | "footer" | "content" | "panel";
+
+const LAYOUT_SLOT = Symbol.for("iwbi.layoutSlot");
+
+type SlotComponent = React.ForwardRefExoticComponent<never> & {
+  [LAYOUT_SLOT]?: LayoutSlotId;
+  render?: { [LAYOUT_SLOT]?: LayoutSlotId };
+  type?: { [LAYOUT_SLOT]?: LayoutSlotId };
+};
+
+function markSlot<T>(component: T, slot: LayoutSlotId): T {
+  (component as T & { [LAYOUT_SLOT]: LayoutSlotId })[LAYOUT_SLOT] = slot;
+  return component;
+}
+
+function slotIdOf(element: React.ReactElement): LayoutSlotId | undefined {
+  const type = element.type;
+  if (typeof type === "string" || typeof type === "number") return undefined;
+  const tagged = type as SlotComponent;
+  return (
+    tagged[LAYOUT_SLOT] ??
+    tagged.render?.[LAYOUT_SLOT] ??
+    tagged.type?.[LAYOUT_SLOT]
+  );
+}
+
+interface LayoutHeaderProps extends LayoutSlotHTMLProps {
+  /** Kept narrow so the landmark cannot be lost by accident. */
+  as?: "header" | "div";
+}
+
+const LayoutHeader = markSlot(
+  React.forwardRef<HTMLElement, LayoutHeaderProps>(
+    ({ as = "header", ...props }, ref) => {
+      const Component = as as React.ElementType;
+      return <Component ref={ref} className="layout-header" {...props} />;
+    },
+  ),
+  "header",
+);
+LayoutHeader.displayName = "LayoutHeader";
+
+interface LayoutFooterProps extends LayoutSlotHTMLProps {
+  /** Kept narrow so the landmark cannot be lost by accident. */
+  as?: "footer" | "div";
+}
+
+const LayoutFooter = markSlot(
+  React.forwardRef<HTMLElement, LayoutFooterProps>(
+    ({ as = "footer", ...props }, ref) => {
+      const Component = as as React.ElementType;
+      return <Component ref={ref} className="layout-footer" {...props} />;
+    },
+  ),
+  "footer",
+);
+LayoutFooter.displayName = "LayoutFooter";
+
+interface LayoutContentProps extends LayoutSlotHTMLProps {
+  /** Kept narrow so the landmark cannot be lost by accident. */
+  as?: "main" | "div";
+  isScrollable?: boolean;
+}
+
+const LayoutContent = markSlot(
+  React.forwardRef<HTMLElement, LayoutContentProps>(
+    ({ as = "main", isScrollable = true, tabIndex, ...props }, ref) => {
+      const Component = as as React.ElementType;
+      return (
+        <Component
+          ref={ref}
+          className={cn(
+            "layout-content",
+            isScrollable && "layout-content--scrollable",
+          )}
+          tabIndex={tabIndex ?? (isScrollable ? 0 : undefined)}
+          {...props}
+        />
+      );
+    },
+  ),
+  "content",
+);
+LayoutContent.displayName = "LayoutContent";
+
+interface LayoutPanelProps extends LayoutSlotHTMLProps {
+  /** Kept narrow so the landmark cannot be lost by accident. */
+  as?: "aside" | "nav" | "div";
+  placement?: LayoutPanelPlacement;
+  /** Named width backed by `--layout-panel-width-*`. Default `default` (17.5rem). */
+  width?: LayoutPanelWidth;
+  /** Named inset backed by `--layout-panel-padding`. Default `xl`. */
+  padding?: SpaceName;
+  isScrollable?: boolean;
+}
+
+const LayoutPanel = markSlot(
+  React.forwardRef<HTMLElement, LayoutPanelProps>(
+    (
+      {
+        as = "aside",
+        placement = "start",
+        width,
+        padding,
+        isScrollable = true,
+        tabIndex,
+        "aria-label": ariaLabel,
+        ...props
+      },
+      ref,
+    ) => {
+      const Component = as as React.ElementType;
+      return (
+        <Component
+          ref={ref}
+          className={cn(
+            "layout-panel",
+            `layout-panel--${placement}`,
+            isScrollable && "layout-panel--scrollable",
+          )}
+          style={{
+            ...(width != null
+              ? { ["--layout-panel-width" as string]: panelWidthVar(width) }
+              : undefined),
+            ...(padding != null
+              ? { ["--layout-panel-padding" as string]: tokenCss(padding) }
+              : undefined),
+          }}
+          tabIndex={tabIndex ?? (isScrollable ? 0 : undefined)}
+          aria-label={
+            ariaLabel ?? (placement === "end" ? "Details" : "Navigation")
+          }
+          {...props}
+        />
+      );
+    },
+  ),
+  "panel",
+);
+LayoutPanel.displayName = "LayoutPanel";
+
+interface LayoutProps extends LayoutSlotHTMLProps<HTMLDivElement> {
+  height?: LayoutHeight;
+  /** Named measure backed by `--layout-measure-*`. Caps and centers the main column. */
+  contentWidth?: LayoutMeasure;
+  /** Named inset for header/footer (horizontal) and content (all sides). Default `2xl`. Panels use their own `padding`. */
+  padding?: SpaceName;
+}
+
+type LayoutSlots = {
+  header?: React.ReactNode;
+  footer?: React.ReactNode;
+  start?: React.ReactNode;
+  end?: React.ReactNode;
+  content?: React.ReactNode;
+};
+
+function collectSlots(children: React.ReactNode): LayoutSlots {
+  const slots: LayoutSlots = {};
+  const leftovers: React.ReactNode[] = [];
+  let sawStartPanel = false;
+
+  React.Children.forEach(children, (child) => {
+    if (!React.isValidElement(child)) {
+      leftovers.push(child);
+      return;
+    }
+    const slot = slotIdOf(child);
+    if (slot === "header" && slots.header == null) {
+      slots.header = child;
+      return;
+    }
+    if (slot === "footer" && slots.footer == null) {
+      slots.footer = child;
+      return;
+    }
+    if (slot === "content" && slots.content == null) {
+      slots.content = child;
+      return;
+    }
+    if (slot === "panel") {
+      const placement =
+        (child.props as LayoutPanelProps).placement ??
+        (sawStartPanel ? "end" : "start");
+      if (placement === "end" && slots.end == null) {
+        slots.end = child;
+        return;
+      }
+      if (slots.start == null) {
+        slots.start = child;
+        sawStartPanel = true;
+        return;
+      }
+      if (slots.end == null) {
+        slots.end = child;
+        return;
+      }
+    }
+    leftovers.push(child);
+  });
+
+  if (leftovers.length > 0) {
+    if (process.env.NODE_ENV !== "production") {
+      console.warn(
+        "Layout: child was not LayoutHeader, LayoutFooter, LayoutContent, or LayoutPanel.",
+        leftovers,
+      );
+    }
+    if (slots.content == null) {
+      slots.content = leftovers.length === 1 ? leftovers[0] : leftovers;
+    }
+  }
+
+  return slots;
+}
+
+const Layout = React.forwardRef<HTMLDivElement, LayoutProps>(
+  (
+    { children, height = "fill", contentWidth, padding = "2xl", ...props },
+    ref,
+  ) => {
+    const slots = collectSlots(children);
+
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          "layout",
+          height === "fill" ? "layout--fill" : "layout--auto",
+        )}
+        style={{
+          ["--layout-padding" as string]: gapCss(padding),
+          ...(contentWidth != null
+            ? {
+                ["--layout-content-max-width" as string]:
+                  measureVar(contentWidth),
+              }
+            : undefined),
+        }}
+        {...props}
+      >
+        {slots.header}
+        {slots.start}
+        {slots.content != null &&
+          (React.isValidElement(slots.content) &&
+          slotIdOf(slots.content as React.ReactElement) === "content" ? (
+            slots.content
+          ) : (
+            <LayoutContent>{slots.content}</LayoutContent>
+          ))}
+        {slots.end}
+        {slots.footer}
+      </div>
+    );
+  },
+);
+Layout.displayName = "Layout";
+
+// ---------------------------------------------------------------------------
+// Container — max-width wrapper (kept; prefer Center / Layout contentWidth)
+// ---------------------------------------------------------------------------
+
+type ContainerSize = "sm" | "md" | "lg" | "xl" | "2xl" | "full";
+
+interface ContainerProps extends React.HTMLAttributes<HTMLElement> {
+  as?: React.ElementType;
+  size?: ContainerSize;
+  center?: boolean;
+  padded?: boolean;
+}
+
+const Container = React.forwardRef<HTMLElement, ContainerProps>(
+  (
+    {
+      as: Component = "div",
+      size = "xl",
+      center = true,
+      padded = true,
+      className,
+      ...props
+    },
+    ref,
+  ) => (
+    <Component
+      ref={ref}
+      className={cn(
+        "container-layout",
+        `container-layout--${size}`,
+        center && "container-layout--center",
+        padded && "container-layout--padded",
+        className,
+      )}
+      {...props}
+    />
+  ),
+);
+Container.displayName = "Container";
+
+// ---------------------------------------------------------------------------
+// Show / Hide
+// ---------------------------------------------------------------------------
+
+type Breakpoint = "sm" | "md" | "lg" | "xl";
+
+interface ShowProps extends React.HTMLAttributes<HTMLDivElement> {
+  above?: Breakpoint;
+  below?: Breakpoint;
+  as?: React.ElementType;
+}
+
+const Show = React.forwardRef<HTMLDivElement, ShowProps>(
+  ({ above, below, as: Component = "div", className, ...props }, ref) => (
+    <Component
+      ref={ref}
+      className={cn(
+        above && `show-above-${above}`,
+        below && `show-below-${below}`,
+        className,
+      )}
+      {...props}
+    />
+  ),
+);
+Show.displayName = "Show";
+
+interface HideProps extends React.HTMLAttributes<HTMLDivElement> {
+  above?: Breakpoint;
+  below?: Breakpoint;
+  as?: React.ElementType;
+}
+
+const Hide = React.forwardRef<HTMLDivElement, HideProps>(
+  ({ above, below, as: Component = "div", className, ...props }, ref) => (
+    <Component
+      ref={ref}
+      className={cn(
+        above && `hide-above-${above}`,
+        below && `hide-below-${below}`,
+        className,
+      )}
+      {...props}
+    />
+  ),
+);
+Hide.displayName = "Hide";
+
+// ---------------------------------------------------------------------------
+// Positioned / Spacer
+// ---------------------------------------------------------------------------
+
+type PositionType = "relative" | "absolute" | "fixed" | "sticky";
+
+interface PositionedProps extends React.HTMLAttributes<HTMLElement> {
+  as?: React.ElementType;
+  position?: PositionType;
+  top?: number | string;
+  right?: number | string;
+  bottom?: number | string;
+  left?: number | string;
+  inset?: number | string;
+  zIndex?: number;
+  fill?: boolean;
+}
+
+const Positioned = React.forwardRef<HTMLElement, PositionedProps>(
+  (
+    {
+      as: Component = "div",
+      position = "relative",
+      top,
+      right,
+      bottom,
+      left,
+      inset,
+      zIndex,
+      fill = false,
+      className,
+      style,
+      ...props
+    },
+    ref,
+  ) => {
+    const resolveValue = (v: number | string | undefined) =>
+      v === undefined ? undefined : typeof v === "number" ? spacing(v) : v;
+
+    return (
+      <Component
+        ref={ref}
+        className={cn(`positioned--${position}`, className)}
+        style={{
+          top: resolveValue(top),
+          right: resolveValue(right),
+          bottom: resolveValue(bottom),
+          left: resolveValue(left),
+          inset: fill ? 0 : resolveValue(inset),
+          zIndex,
+          ...style,
+        }}
+        {...props}
+      />
+    );
+  },
+);
+Positioned.displayName = "Positioned";
+
+export type SpacerSpace = SpaceName | SpacerSpacePx;
+export type SpacerAxis = "horizontal" | "vertical";
+
+function spacerTokenCss(space?: SpacerSpace, size?: number): string {
+  if (typeof space === "string") return tokenCss(space);
+  if (typeof space === "number") {
+    const named = PX_TO_SPACE[space];
+    return named ? tokenCss(named) : `${space}px`;
+  }
+  if (size != null) {
+    const px = size * 4;
+    const named = PX_TO_SPACE[px as SpacerSpacePx];
+    return named ? tokenCss(named) : spacing(size);
+  }
+  return tokenCss("md");
+}
+
+interface SpacerProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Named token (`md`) or legacy px (`16`). Default `md`. */
+  space?: SpacerSpace;
+  /**
+   * @deprecated 4px units (`size={4}` → 16px / `md`). Prefer `space="md"`.
+   */
+  size?: number;
+  axis?: SpacerAxis;
+  /** Grow to fill leftover space in a stack. Ignores `space` / `axis`. */
+  flex?: boolean;
+}
+
+const Spacer = ({
+  space,
+  size,
+  axis = "vertical",
+  flex = false,
+  className,
+  style,
+  ...props
+}: SpacerProps) => {
+  const token = spacerTokenCss(space, size);
+  return (
+    <div
+      aria-hidden="true"
+      className={cn(
+        "spacer",
+        flex
+          ? "spacer--flex"
+          : axis === "horizontal"
+            ? "spacer--horizontal"
+            : "spacer--vertical",
+        className,
+      )}
+      style={{
+        ...(flex
+          ? undefined
+          : axis === "vertical"
+            ? { height: token, minHeight: token }
+            : { width: token, minWidth: token }),
+        ...style,
+      }}
+      {...props}
+    />
+  );
+};
+Spacer.displayName = "Spacer";
+
+export {
+  Stack,
+  HStack,
+  VStack,
+  StackItem,
+  Grid,
+  GridSpan,
+  Columns,
+  Center,
+  FormLayout,
+  Section,
+  Layout,
+  LayoutHeader,
+  LayoutFooter,
+  LayoutContent,
+  LayoutPanel,
+  Container,
+  Show,
+  Hide,
+  Positioned,
+  Spacer,
+  // Previous names — keep working until remaining stories migrate
+  Layout as AppShell,
+  LayoutHeader as AppShellHeader,
+  LayoutPanel as AppShellSidebar,
+  LayoutContent as AppShellMain,
+  LayoutFooter as AppShellFooter,
+};
+
+export type {
+  StackProps,
+  HStackProps,
+  VStackProps,
+  StackItemProps,
+  GridProps,
+  GridSpanProps,
+  ColumnsProps,
+  CenterProps,
+  FormLayoutProps,
+  SectionProps,
+  LayoutProps,
+  LayoutHeaderProps,
+  LayoutFooterProps,
+  LayoutContentProps,
+  LayoutPanelProps,
+  ContainerProps,
+  ShowProps,
+  HideProps,
+  PositionedProps,
+  SpacerProps,
+  LayoutHeight,
+  LayoutPanelWidth,
+  LayoutPanelPlacement,
+  LayoutMeasure,
+  CenterAxis,
+  FormLayoutDirection,
+  LayoutProps as AppShellProps,
+};