@flikk/ui 1.0.0-beta.3 → 1.0.0-beta.31

package/dist/components/generative/validate.js

@@ -0,0 +1,351 @@
+import { GENERATIVE_SCHEMA } from './schema.generated.js';
+
+/** Props that are NEVER accepted from a spec, regardless of schema. */
+const BLOCKED_PROPS = new Set(["className", "style", "ref", "key", "theme", "dangerouslySetInnerHTML"]);
+/**
+ * Keys that hijack the prototype chain when used as an assignment target
+ * (`obj["__proto__"] = v` invokes the setter; `constructor`/`prototype` shadow).
+ * They must never be written into a rebuilt object from spec input — denied at
+ * every dynamic-write site with a recorded issue, since `safeLookup` only guards
+ * the read/lookup sites.
+ */
+const PROTO_POLLUTION_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+/**
+ * Any prop whose name begins with "on" (case-insensitively) is treated as a
+ * DOM/React event handler and blocked, regardless of casing — `onClick`,
+ * `onclick`, `ONLOAD`, `oNcLiCk` are all the same injection vector. This is
+ * intentionally broader than the exact-case convention: the curated schema
+ * has no legitimate prop that starts with "on" (verified against
+ * `schema.generated.ts`), so there is no allow-listed prop this can
+ * newly/incorrectly block.
+ */
+const isHandler = (key) => /^on[a-z]/i.test(key);
+/** Recursion guard for both the node tree and nested structured prop values. */
+const MAX_DEPTH = 100;
+/**
+ * Safe lookup on a plain object used as a string-keyed map. Guards against
+ * Object.prototype-colliding keys ("constructor", "toString", "__proto__",
+ * "hasOwnProperty", …) resolving an INHERITED member instead of `undefined` —
+ * which would otherwise let an unknown key silently skip its "not found"
+ * branch (or crash downstream code that assumes a `ComponentSchema`/`SchemaProp`).
+ */
+function safeLookup(map, key) {
+    return Object.hasOwn(map, key) ? map[key] : undefined;
+}
+/**
+ * Recursively strip blocked keys / function values from an arbitrary value
+ * nested inside a structured ("shape") prop — chartConfig, donutColors,
+ * gridCols breakpoint maps, and each item of array-of-object shapes
+ * (tableColumns, accordionItems, …) all funnel through this so the injection
+ * guard applies at every depth, not just the top-level props map. Never
+ * throws; bottoms out at MAX_DEPTH rather than recursing unboundedly.
+ */
+function sanitizeStructuredValue(value, path, issues, depth = 0) {
+    if (depth > MAX_DEPTH) {
+        issues.push({
+            path,
+            code: "max-depth-exceeded",
+            severity: "warning",
+            message: `Maximum nesting depth (${MAX_DEPTH}) exceeded — value pruned`,
+        });
+        return undefined;
+    }
+    if (typeof value === "function") {
+        issues.push({
+            path,
+            code: "blocked-prop",
+            severity: "warning",
+            message: "Function value is not accepted from a spec (injection guard) — removed",
+        });
+        return undefined;
+    }
+    if (Array.isArray(value)) {
+        return value
+            .map((v, i) => sanitizeStructuredValue(v, `${path}[${i}]`, issues, depth + 1))
+            .filter((v) => v !== undefined);
+    }
+    if (value !== null && typeof value === "object") {
+        const next = {};
+        for (const [k, v] of Object.entries(value)) {
+            if (BLOCKED_PROPS.has(k) || isHandler(k) || PROTO_POLLUTION_KEYS.has(k)) {
+                issues.push({
+                    path: `${path}.${k}`,
+                    code: "blocked-prop",
+                    severity: "warning",
+                    message: `"${k}" removed (injection guard)`,
+                });
+                continue;
+            }
+            const sanitized = sanitizeStructuredValue(v, `${path}.${k}`, issues, depth + 1);
+            if (sanitized !== undefined)
+                next[k] = sanitized;
+        }
+        return next;
+    }
+    return value;
+}
+/**
+ * Validate + repair a model-emitted spec against the generated schema.
+ * Never throws; never mutates the input. Every repair is recorded in `issues`.
+ * Unknown components are kept (GenerativeView renders its safe placeholder)
+ * but their props/children are stripped.
+ */
+function validate(spec, options = {}) {
+    var _a;
+    const schema = (_a = options.schema) !== null && _a !== void 0 ? _a : GENERATIVE_SCHEMA;
+    const issues = [];
+    if (Array.isArray(spec)) {
+        return { spec: spec.map((n, i) => validateNode(n, schema, `$[${i}]`, issues, 0)), issues };
+    }
+    return { spec: validateNode(spec, schema, "$", issues, 0), issues };
+}
+function validateNode(node, schema, path, issues, depth) {
+    if (depth > MAX_DEPTH) {
+        issues.push({
+            path,
+            code: "max-depth-exceeded",
+            severity: "error",
+            message: `Maximum nesting depth (${MAX_DEPTH}) exceeded — node pruned`,
+        });
+        return { component: "__invalid__" };
+    }
+    if (!node || typeof node !== "object" || typeof node.component !== "string") {
+        issues.push({ path, code: "invalid-node", severity: "error", message: "Node is not an object with a string `component`" });
+        return { component: "__invalid__" };
+    }
+    const raw = node;
+    const comp = safeLookup(schema.components, raw.component);
+    if (!comp) {
+        issues.push({
+            path,
+            code: "unknown-component",
+            severity: "error",
+            message: `Unknown component "${raw.component}" — props/children stripped; renders as placeholder`,
+        });
+        return { component: raw.component, ...(raw.id ? { id: raw.id } : {}) };
+    }
+    const props = sanitizeProps(raw.props, comp, schema, path, issues);
+    // Fill required props that have a schema default; flag the rest.
+    for (const [name, ps] of Object.entries(comp.props)) {
+        if (!ps.required || props[name] !== undefined)
+            continue;
+        if (ps.default !== undefined) {
+            props[name] = ps.default;
+            issues.push({
+                path: `${path}.props.${name}`,
+                code: "applied-default",
+                severity: "warning",
+                message: `Required prop "${name}" missing — applied default ${JSON.stringify(ps.default)}`,
+            });
+        }
+        else {
+            issues.push({
+                path: `${path}.props.${name}`,
+                code: "missing-required",
+                severity: "error",
+                message: `Required prop "${name}" is missing`,
+            });
+        }
+    }
+    let children;
+    if (Array.isArray(raw.children) && raw.children.length) {
+        if (comp.role !== "container") {
+            issues.push({
+                path: `${path}.children`,
+                code: "children-ignored",
+                severity: "warning",
+                message: `"${raw.component}" is not a container — children removed`,
+            });
+        }
+        else {
+            children = raw.children.map((c, i) => validateNode(c, schema, `${path}.children[${i}]`, issues, depth + 1));
+        }
+    }
+    let actions;
+    if (raw.actions && typeof raw.actions === "object") {
+        for (const [key, descriptor] of Object.entries(raw.actions)) {
+            if (PROTO_POLLUTION_KEYS.has(key)) {
+                issues.push({
+                    path: `${path}.actions.${key}`,
+                    code: "blocked-prop",
+                    severity: "warning",
+                    message: `Action name "${key}" removed (injection guard)`,
+                });
+                continue;
+            }
+            if (descriptor && typeof descriptor === "object" && typeof descriptor.type === "string") {
+                const payload = descriptor.payload !== undefined
+                    ? sanitizeStructuredValue(descriptor.payload, `${path}.actions.${key}.payload`, issues)
+                    : undefined;
+                (actions !== null && actions !== void 0 ? actions : (actions = {}))[key] = {
+                    type: descriptor.type,
+                    ...(payload !== undefined ? { payload } : {}),
+                };
+            }
+            else {
+                issues.push({
+                    path: `${path}.actions.${key}`,
+                    code: "invalid-action",
+                    severity: "warning",
+                    message: `Action "${key}" must be { type: string, payload? } — removed`,
+                });
+            }
+        }
+    }
+    return {
+        component: raw.component,
+        ...(raw.id ? { id: raw.id } : {}),
+        ...(raw.sizeHint ? { sizeHint: raw.sizeHint } : {}),
+        ...(Object.keys(props).length ? { props } : {}),
+        ...(children ? { children } : {}),
+        ...(actions ? { actions } : {}),
+    };
+}
+function sanitizeProps(rawProps, comp, schema, path, issues) {
+    const out = {};
+    for (const [key, value] of Object.entries(rawProps !== null && rawProps !== void 0 ? rawProps : {})) {
+        const propPath = `${path}.props.${key}`;
+        if (BLOCKED_PROPS.has(key) || isHandler(key)) {
+            issues.push({
+                path: propPath,
+                code: "blocked-prop",
+                severity: "warning",
+                message: `"${key}" is not accepted from a spec (injection guard) — removed`,
+            });
+            continue;
+        }
+        const ps = safeLookup(comp.props, key);
+        if (!ps) {
+            issues.push({
+                path: propPath,
+                code: "unknown-prop",
+                severity: "warning",
+                message: `"${key}" is not in the contract — removed (allow-list)`,
+            });
+            continue;
+        }
+        const checked = checkValue(key, value, ps, schema, propPath, issues);
+        if (checked !== undefined)
+            out[key] = checked;
+    }
+    return out;
+}
+function checkValue(key, value, ps, schema, path, issues) {
+    var _a, _b;
+    const drop = (message, code = "invalid-value") => {
+        if (ps.default !== undefined) {
+            issues.push({ path, code, severity: "warning", message: `${message} — replaced with default ${JSON.stringify(ps.default)}` });
+            return ps.default;
+        }
+        issues.push({ path, code, severity: "warning", message: `${message} — removed` });
+        return undefined;
+    };
+    switch (ps.kind) {
+        case "enum": {
+            const options = (_a = ps.options) !== null && _a !== void 0 ? _a : [];
+            if (options.includes(value))
+                return value;
+            if (typeof value === "string") {
+                const ci = options.find((o) => typeof o === "string" && o.toLowerCase() === value.toLowerCase());
+                if (ci !== undefined) {
+                    issues.push({ path, code: "coerced-value", severity: "warning", message: `"${value}" coerced to "${ci}"` });
+                    return ci;
+                }
+                const num = Number(value);
+                if (!Number.isNaN(num) && options.includes(num)) {
+                    issues.push({ path, code: "coerced-value", severity: "warning", message: `"${value}" coerced to ${num}` });
+                    return num;
+                }
+            }
+            return drop(`${JSON.stringify(value)} is not one of ${JSON.stringify(options)}`, "invalid-enum");
+        }
+        case "boolean": {
+            if (typeof value === "boolean")
+                return value;
+            if (value === "true" || value === "false") {
+                issues.push({ path, code: "coerced-value", severity: "warning", message: `"${value}" coerced to boolean` });
+                return value === "true";
+            }
+            return drop(`Expected boolean, got ${JSON.stringify(value)}`);
+        }
+        case "number": {
+            if (typeof value === "number")
+                return value;
+            if (typeof value === "string" && value.trim() !== "" && !Number.isNaN(Number(value))) {
+                issues.push({ path, code: "coerced-value", severity: "warning", message: `"${value}" coerced to number` });
+                return Number(value);
+            }
+            return drop(`Expected number, got ${JSON.stringify(value)}`);
+        }
+        case "string":
+        case "text": {
+            if (typeof value === "string")
+                return value;
+            if (typeof value === "number" || typeof value === "boolean") {
+                issues.push({ path, code: "coerced-value", severity: "warning", message: `${JSON.stringify(value)} coerced to string` });
+                return String(value);
+            }
+            return drop(`Expected string, got ${JSON.stringify(value)}`);
+        }
+        case "union": {
+            const types = (_b = ps.types) !== null && _b !== void 0 ? _b : [];
+            if (types.includes(typeof value))
+                return value;
+            if (types.includes("number") && typeof value === "string" && value.trim() !== "" && !Number.isNaN(Number(value))) {
+                issues.push({ path, code: "coerced-value", severity: "warning", message: `"${value}" coerced to number` });
+                return Number(value);
+            }
+            if (types.includes("string") && (typeof value === "number" || typeof value === "boolean")) {
+                issues.push({ path, code: "coerced-value", severity: "warning", message: `${JSON.stringify(value)} coerced to string` });
+                return String(value);
+            }
+            return drop(`Expected ${types.join(" | ")}, got ${JSON.stringify(value)}`);
+        }
+        case "icon": {
+            if (typeof value !== "string")
+                return drop(`Icon must be a NAME string, got ${JSON.stringify(value)}`);
+            if (schema.icons.includes(value))
+                return value;
+            const ci = schema.icons.find((n) => n.toLowerCase() === value.toLowerCase());
+            if (ci) {
+                issues.push({ path, code: "coerced-value", severity: "warning", message: `Icon "${value}" coerced to "${ci}"` });
+                return ci;
+            }
+            return drop(`Unknown icon "${value}" (closed set of ${schema.icons.length})`, "invalid-enum");
+        }
+        case "shape": {
+            if (ps.shape === "gridCols") {
+                if (typeof value === "number")
+                    return value;
+                if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+                    return sanitizeStructuredValue(value, path, issues);
+                }
+                return drop(`Expected a number or breakpoint map, got ${JSON.stringify(value)}`, "invalid-shape");
+            }
+            if (ps.shape === "chartConfig" || ps.shape === "donutColors") {
+                if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+                    return sanitizeStructuredValue(value, path, issues);
+                }
+                return drop(`Expected an object, got ${JSON.stringify(value)}`, "invalid-shape");
+            }
+            // every other shape is an array of objects
+            if (!Array.isArray(value))
+                return drop(`Expected an array, got ${JSON.stringify(value)}`, "invalid-shape");
+            const cleaned = value.filter((item) => item !== null && typeof item === "object" && !Array.isArray(item));
+            if (cleaned.length !== value.length) {
+                issues.push({
+                    path,
+                    code: "invalid-shape",
+                    severity: "warning",
+                    message: `${value.length - cleaned.length} non-object item(s) removed from "${key}"`,
+                });
+            }
+            // strip blocked/handler keys (recursively, at any depth) inside structured items
+            return cleaned
+                .map((item, i) => sanitizeStructuredValue(item, `${path}[${i}]`, issues))
+                .filter((v) => v !== undefined);
+        }
+    }
+}
+
+export { validate };

package/dist/components/generative/validate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/layout/AppShell/AppShell.d.ts

@@ -0,0 +1,10 @@
+import React from "react";
+import type { AppShellProps } from "./AppShell.types";
+export declare const AppShell: React.ForwardRefExoticComponent<AppShellProps & React.RefAttributes<HTMLDivElement>> & {
+    Topbar: React.ForwardRefExoticComponent<import("./AppShell.types").AppShellTopbarProps & React.RefAttributes<HTMLElement>>;
+    Sidebar: React.ForwardRefExoticComponent<import("./AppShell.types").AppShellSidebarProps & React.RefAttributes<HTMLElement>>;
+    Header: React.ForwardRefExoticComponent<import("./AppShell.types").AppShellHeaderProps & React.RefAttributes<HTMLElement>>;
+    Main: React.ForwardRefExoticComponent<import("./AppShell.types").AppShellMainProps & React.RefAttributes<HTMLElement>>;
+    RightPanel: React.ForwardRefExoticComponent<import("./AppShell.types").AppShellRightPanelProps & React.RefAttributes<HTMLElement>>;
+    Footer: React.ForwardRefExoticComponent<import("./AppShell.types").AppShellFooterProps & React.RefAttributes<HTMLElement>>;
+};

package/dist/components/layout/AppShell/AppShell.js

@@ -0,0 +1,85 @@
+"use client";
+import { jsx, jsxs } from 'react/jsx-runtime';
+import React__default from 'react';
+import { cn } from '../../../utils/cn.js';
+import { getAppShellTheme } from './AppShell.theme.js';
+import { AppShellProvider } from './AppShellContext.js';
+import { AppShellTopbar } from './AppShellTopbar.js';
+import { AppShellSidebar } from './AppShellSidebar.js';
+import { AppShellHeader } from './AppShellHeader.js';
+import { AppShellMain } from './AppShellMain.js';
+import { AppShellRightPanel } from './AppShellRightPanel.js';
+import { AppShellFooter } from './AppShellFooter.js';
+
+const AppShellRoot = React__default.forwardRef(({ className, theme: customTheme, scroll = "viewport", topbarSpan = "full", footerSpan = "full", contentWidth = "full", contentPadding = "md", children, ...props }, ref) => {
+    const theme = getAppShellTheme(customTheme);
+    const contextValue = React__default.useMemo(() => ({ scroll, contentWidth, contentPadding }), [scroll, contentWidth, contentPadding]);
+    // Bucket children by slot type. Header is intentionally NOT bucketed —
+    // it is user-composed inside AppShell.Main.
+    let topbar = null;
+    let sidebar = null;
+    let main = null;
+    let rightPanel = null;
+    let footer = null;
+    React__default.Children.forEach(children, (child) => {
+        if (!React__default.isValidElement(child))
+            return;
+        const type = child.type;
+        if (type === AppShellTopbar) {
+            if (topbar === null)
+                topbar = child;
+            else if (process.env.NODE_ENV !== "production") {
+                console.warn("[AppShell]: multiple AppShell.Topbar children; keeping the first.");
+            }
+        }
+        else if (type === AppShellSidebar) {
+            if (sidebar === null)
+                sidebar = child;
+            else if (process.env.NODE_ENV !== "production") {
+                console.warn("[AppShell]: multiple AppShell.Sidebar children; keeping the first.");
+            }
+        }
+        else if (type === AppShellMain) {
+            if (main === null)
+                main = child;
+            else if (process.env.NODE_ENV !== "production") {
+                console.warn("[AppShell]: multiple AppShell.Main children; keeping the first.");
+            }
+        }
+        else if (type === AppShellRightPanel) {
+            if (rightPanel === null)
+                rightPanel = child;
+            else if (process.env.NODE_ENV !== "production") {
+                console.warn("[AppShell]: multiple AppShell.RightPanel children; keeping the first.");
+            }
+        }
+        else if (type === AppShellFooter) {
+            if (footer === null)
+                footer = child;
+            else if (process.env.NODE_ENV !== "production") {
+                console.warn("[AppShell]: multiple AppShell.Footer children; keeping the first.");
+            }
+        }
+        else if (process.env.NODE_ENV !== "production") {
+            console.warn("[AppShell]: unknown child rendered; expected one of " +
+                "AppShell.Topbar / Sidebar / Main / RightPanel / Footer. " +
+                "AppShell.Header is composed inside AppShell.Main.");
+        }
+    });
+    const topbarInChrome = topbar !== null && topbarSpan === "full";
+    const topbarInMain = topbar !== null && topbarSpan === "main";
+    const footerInChrome = footer !== null && footerSpan === "full";
+    const footerInMain = footer !== null && footerSpan === "main";
+    return (jsx(AppShellProvider, { value: contextValue, children: jsxs("div", { ref: ref, className: cn(theme.root, scroll === "viewport" && theme.rootViewport, className), ...props, children: [topbarInChrome && topbar, jsxs("div", { className: theme.shell, children: [sidebar, jsxs("div", { className: theme.mainColumn, children: [topbarInMain && topbar, main, footerInMain && footer] }), rightPanel] }), footerInChrome && footer] }) }));
+});
+AppShellRoot.displayName = "AppShell";
+const AppShell = Object.assign(AppShellRoot, {
+    Topbar: AppShellTopbar,
+    Sidebar: AppShellSidebar,
+    Header: AppShellHeader,
+    Main: AppShellMain,
+    RightPanel: AppShellRightPanel,
+    Footer: AppShellFooter,
+});
+
+export { AppShell };

package/dist/components/layout/AppShell/AppShell.theme.d.ts

@@ -0,0 +1,3 @@
+import type { AppShellTheme, AppShellThemeOverrides } from "./AppShell.types";
+export declare const appShellTheme: AppShellTheme;
+export declare const getAppShellTheme: (customTheme?: AppShellThemeOverrides) => AppShellTheme;

package/dist/components/layout/AppShell/AppShell.theme.js

@@ -0,0 +1,42 @@
+const appShellTheme = {
+    root: "flex flex-col bg-[var(--color-background)] text-[var(--color-text-primary)]",
+    rootViewport: "h-screen overflow-hidden",
+    shell: "flex flex-1 min-h-0 min-w-0",
+    mainColumn: "flex flex-col flex-1 min-h-0 min-w-0",
+    topbar: "shrink-0 border-b border-[var(--color-border)] bg-[var(--color-background)]/90 backdrop-blur supports-[backdrop-filter]:bg-[var(--color-background)]/75",
+    sidebar: "flex flex-col shrink-0 overflow-hidden",
+    sidebarScroll: "min-h-0 flex-1",
+    sidebarCollapsed: "hidden lg:flex",
+    header: "shrink-0 border-b border-[var(--color-border)] bg-[var(--color-background)]/90 backdrop-blur supports-[backdrop-filter]:bg-[var(--color-background)]/75",
+    main: "flex flex-col flex-1 min-h-0 min-w-0",
+    mainScroll: "min-h-0 flex-1",
+    mainInner: "mx-auto w-full",
+    rightPanel: "flex flex-col shrink-0 overflow-hidden border-l border-[var(--color-border)]",
+    rightPanelScroll: "min-h-0 flex-1",
+    footer: "shrink-0 border-t border-[var(--color-border)] bg-[var(--color-background)]/90 backdrop-blur supports-[backdrop-filter]:bg-[var(--color-background)]/75",
+    contentPadding: {
+        none: "p-0",
+        sm: "p-3 sm:p-4",
+        md: "p-4 sm:p-6 lg:p-8",
+        lg: "p-5 sm:p-8 lg:p-10",
+    },
+    contentWidth: {
+        full: "max-w-none",
+        wide: "max-w-7xl",
+        contained: "max-w-5xl",
+    },
+};
+const getAppShellTheme = (customTheme) => ({
+    ...appShellTheme,
+    ...customTheme,
+    contentPadding: {
+        ...appShellTheme.contentPadding,
+        ...customTheme === null || customTheme === void 0 ? void 0 : customTheme.contentPadding,
+    },
+    contentWidth: {
+        ...appShellTheme.contentWidth,
+        ...customTheme === null || customTheme === void 0 ? void 0 : customTheme.contentWidth,
+    },
+});
+
+export { appShellTheme, getAppShellTheme };

package/dist/components/layout/AppShell/AppShell.types.d.ts

@@ -0,0 +1,127 @@
+import React from "react";
+export type AppShellScroll = "viewport" | "page";
+export type AppShellSpan = "full" | "main";
+export type AppShellContentWidth = "full" | "wide" | "contained";
+export type AppShellContentPadding = "none" | "sm" | "md" | "lg";
+export interface AppShellTheme {
+    /** Outer root container (column layout). */
+    root: string;
+    /** Extra classes applied when `scroll="viewport"`. */
+    rootViewport: string;
+    /** Row container holding sidebar / main column / right panel. */
+    shell: string;
+    /** The middle column (Topbar-in-main? Main, Footer-in-main?). */
+    mainColumn: string;
+    topbar: string;
+    sidebar: string;
+    sidebarScroll: string;
+    sidebarCollapsed: string;
+    header: string;
+    main: string;
+    mainScroll: string;
+    mainInner: string;
+    rightPanel: string;
+    rightPanelScroll: string;
+    footer: string;
+    contentPadding: Record<AppShellContentPadding, string>;
+    contentWidth: Record<AppShellContentWidth, string>;
+}
+export interface AppShellThemeOverrides {
+    root?: string;
+    rootViewport?: string;
+    shell?: string;
+    mainColumn?: string;
+    topbar?: string;
+    sidebar?: string;
+    sidebarScroll?: string;
+    sidebarCollapsed?: string;
+    header?: string;
+    main?: string;
+    mainScroll?: string;
+    mainInner?: string;
+    rightPanel?: string;
+    rightPanelScroll?: string;
+    footer?: string;
+    contentPadding?: Partial<Record<AppShellContentPadding, string>>;
+    contentWidth?: Partial<Record<AppShellContentWidth, string>>;
+}
+export interface AppShellProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * Scroll model. `"viewport"` makes the root `h-screen overflow-hidden`
+     * and only `Main` scrolls. `"page"` lets the whole document scroll.
+     * @default "viewport"
+     */
+    scroll?: AppShellScroll;
+    /**
+     * Whether the Topbar spans the full viewport width (over the Sidebar)
+     * or only sits above Main + RightPanel.
+     * @default "full"
+     */
+    topbarSpan?: AppShellSpan;
+    /**
+     * Whether the Footer spans the full viewport width (under the Sidebar)
+     * or only sits below Main + RightPanel.
+     * @default "full"
+     */
+    footerSpan?: AppShellSpan;
+    /**
+     * Max content width applied to AppShell.Main when not overridden.
+     * @default "full"
+     */
+    contentWidth?: AppShellContentWidth;
+    /**
+     * Responsive content padding applied to AppShell.Main when not overridden.
+     * @default "md"
+     */
+    contentPadding?: AppShellContentPadding;
+    /**
+     * Theme overrides for the AppShell root wrapper (root, shell, mainColumn).
+     * Style individual slots via their own `theme` props on each sub-component.
+     */
+    theme?: AppShellThemeOverrides;
+}
+export interface AppShellTopbarProps extends React.HTMLAttributes<HTMLElement> {
+    /** Stick to top of chrome. Only meaningful when `scroll="page"`. @default true */
+    sticky?: boolean;
+    /** Theme overrides. */
+    theme?: AppShellThemeOverrides;
+}
+export interface AppShellSidebarProps extends React.HTMLAttributes<HTMLElement> {
+    /** CSS width value. @default "16rem" */
+    width?: string;
+    /** Hide on mobile (below `lg`). @default true */
+    collapsedOnMobile?: boolean;
+    /** Theme overrides. */
+    theme?: AppShellThemeOverrides;
+}
+export interface AppShellHeaderProps extends React.HTMLAttributes<HTMLElement> {
+    /**
+     * Stick to top of the scrolling Main region. Header sticks at its position
+     * inside Main's content padding; for a flush edge-to-edge sticky bar, use
+     * AppShell.Topbar instead.
+     * @default true
+     */
+    sticky?: boolean;
+    /** Theme overrides. */
+    theme?: AppShellThemeOverrides;
+}
+export interface AppShellMainProps extends React.HTMLAttributes<HTMLElement> {
+    /** Max content width. Inherits from AppShell when omitted. */
+    contentWidth?: AppShellContentWidth;
+    /** Responsive padding. Inherits from AppShell when omitted. */
+    contentPadding?: AppShellContentPadding;
+    /** Theme overrides. */
+    theme?: AppShellThemeOverrides;
+}
+export interface AppShellRightPanelProps extends React.HTMLAttributes<HTMLElement> {
+    /** CSS width value. @default "20rem" */
+    width?: string;
+    /** Theme overrides. */
+    theme?: AppShellThemeOverrides;
+}
+export interface AppShellFooterProps extends React.HTMLAttributes<HTMLElement> {
+    /** Stick to bottom of chrome. Only meaningful when `scroll="page"`. @default true */
+    sticky?: boolean;
+    /** Theme overrides. */
+    theme?: AppShellThemeOverrides;
+}

package/dist/components/layout/AppShell/AppShellContext.d.ts

@@ -0,0 +1,14 @@
+import React from "react";
+import type { AppShellContentPadding, AppShellContentWidth, AppShellScroll } from "./AppShell.types";
+export interface AppShellContextValue {
+    scroll: AppShellScroll;
+    contentWidth: AppShellContentWidth;
+    contentPadding: AppShellContentPadding;
+}
+export declare const AppShellProvider: React.Provider<AppShellContextValue | undefined>;
+/**
+ * Reads AppShell root context. Returns sensible defaults when used outside
+ * an `<AppShell>` (so individual slot components remain usable standalone
+ * for testing or partial composition).
+ */
+export declare const useAppShellContext: () => AppShellContextValue;

package/dist/components/layout/AppShell/AppShellContext.js

@@ -0,0 +1,20 @@
+"use client";
+import React__default from 'react';
+
+const AppShellContext = React__default.createContext(undefined);
+const AppShellProvider = AppShellContext.Provider;
+/**
+ * Reads AppShell root context. Returns sensible defaults when used outside
+ * an `<AppShell>` (so individual slot components remain usable standalone
+ * for testing or partial composition).
+ */
+const useAppShellContext = () => {
+    const ctx = React__default.useContext(AppShellContext);
+    return (ctx !== null && ctx !== void 0 ? ctx : {
+        scroll: "viewport",
+        contentWidth: "full",
+        contentPadding: "md",
+    });
+};
+
+export { AppShellProvider, useAppShellContext };

package/dist/components/layout/AppShell/AppShellFooter.d.ts

@@ -0,0 +1,3 @@
+import React from "react";
+import type { AppShellFooterProps } from "./AppShell.types";
+export declare const AppShellFooter: React.ForwardRefExoticComponent<AppShellFooterProps & React.RefAttributes<HTMLElement>>;