@astryxdesign/core 0.0.0-bootstrap.0 → 0.1.0-canary.0b5b49f

package/dist/AppShell/AppShell.d.ts

@@ -0,0 +1,221 @@
+import React from 'react';
+/**
+ * @file AppShell.tsx
+ * @input Uses React, Layout, LayoutHeader, LayoutPanel, LayoutContent, StyleX
+ * @output Exports AppShell component and AppShellProps type
+ * @position Application-level layout shell — the top-level wrapper for any app.
+ *   Composes Layout internally to provide header, sideNav, and main content areas.
+ *   Use for any app that needs a top nav, side navigation, and scrollable content.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/AppShell/AppShell.doc.mjs
+ * - /packages/core/src/AppShell/index.ts
+ * - /packages/core/src/AppShell/AppShell.test.tsx
+ * - /apps/storybook/stories/AppShell.stories.tsx
+ * - /packages/cli/templates/blocks/components/AppShell/ (showcase blocks)
+ */
+import { type ReactNode } from 'react';
+import type { SpacingStep } from '../utils/types';
+import type { BaseProps } from '../BaseProps';
+/**
+ * SideNav breakpoint options.
+ * - `sm`: 640px
+ * - `md`: 768px
+ * - `lg`: 1024px
+ * - `none`: Never auto-collapse
+ */
+export type AppShellBreakpoint = 'sm' | 'md' | 'lg' | 'none';
+/**
+ * Navigation background style:
+ * - `wash`: Nav areas use wash background, no dividers
+ * - `surface`: Nav areas use surface background, no dividers
+ * - `section`: Dividers between nav and content (classic look)
+ * - `elevated`: Wash nav background with elevated surface content + border radius
+ * @default 'elevated'
+ */
+/**
+ * Extensible variant map for AppShell.
+ *
+ * Theme packages can add custom variants via TypeScript module augmentation:
+ * @example
+ * ```
+ * declare module '@astryxdesign/core/AppShell' {
+ *   interface AppShellVariantMap {
+ *     'glass': true;
+ *   }
+ * }
+ * ```
+ */
+export interface AppShellVariantMap {
+    wash: true;
+    surface: true;
+    section: true;
+    elevated: true;
+}
+/**
+ * Navigation background style. Extensible via module augmentation of AppShellVariantMap.
+ */
+export type AppShellVariant = keyof AppShellVariantMap;
+/**
+ * Configuration object for mobile navigation behavior.
+ * Used when you need to customize the auto mobile nav without replacing it entirely.
+ */
+export interface MobileNavConfig {
+    /**
+     * Whether to auto-render the hamburger toggle.
+     * When false, use `<MobileNavToggle />` to place it yourself.
+     * @default true
+     */
+    hasToggle?: boolean;
+    /**
+     * Controlled open state. When provided, AppShell doesn't manage
+     * mobile nav state internally.
+     */
+    isOpen?: boolean;
+    /**
+     * Callback when the mobile nav drawer open state changes.
+     */
+    onOpenChange?: (isOpen: boolean) => void;
+    /**
+     * Custom drawer content. Replaces the auto-generated drawer.
+     * Can be an `<MobileNav>` for full drawer config (title, width, side)
+     * or raw children.
+     */
+    content?: ReactNode;
+    /**
+     * Breakpoint below which mobile nav activates.
+     * @default 'md'
+     */
+    breakpoint?: AppShellBreakpoint;
+    /**
+     * SSR hint: whether the initial render should assume mobile layout.
+     * Seeds the breakpoint state so the server-rendered HTML matches
+     * the client on mobile devices, avoiding a layout flash.
+     *
+     * Derive from the User-Agent header or a device-detection cookie
+     * in a server component, then pass down.
+     *
+     * @default false
+     */
+    defaultIsMobile?: boolean;
+}
+export interface AppShellProps extends BaseProps<HTMLDivElement> {
+    /** Ref forwarded to the root element */
+    ref?: React.Ref<HTMLDivElement>;
+    /**
+     * Navigation background style controlling how nav areas contrast with content.
+     * - `wash`: Nav uses wash background, no dividers
+     * - `surface`: Nav uses surface background, no dividers
+     * - `section`: Dividers between nav and content (classic look)
+     * - `elevated`: Wash nav with elevated surface content area + border radius
+     * @default 'elevated'
+     */
+    variant?: AppShellVariant;
+    /**
+     * Optional banner slot for system-wide announcements.
+     * Renders above the top nav and scrolls away with the page in auto mode.
+     */
+    banner?: ReactNode;
+    /**
+     * Main content area (rendered as `<main>`).
+     */
+    children: ReactNode;
+    /**
+     * Padding for the main content area using the spacing scale.
+     * Set based on the dominant content pattern for the page:
+     * - `4` (16px) — standard padding for forms, settings, text-heavy pages
+     * - `0` — no padding, for dashboards, maps, tables that need edge-to-edge
+     * Override individual sections with `<Section padding={...}>`.
+     * Accepts numeric spacing steps: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.
+     */
+    contentPadding?: SpacingStep;
+    /**
+     * Height behavior:
+     * - `fill`: Shell fills viewport, content scrolls internally (default)
+     * - `auto`: Shell grows with content, page scrolls as a whole
+     * @default 'fill'
+     */
+    height?: 'fill' | 'auto';
+    /**
+     * Mobile navigation configuration.
+     *
+     * Accepts three shapes:
+     * - **`false`** — Disable mobile nav entirely.
+     * - **`MobileNavConfig` object** — Configure auto behavior (toggle, controlled state, custom content).
+     * - **`ReactNode`** — Full escape hatch: provide your own `<MobileNav>` (you own everything).
+     *
+     * When omitted, AppShell automatically generates a mobile drawer with
+     * sideNav content (and TopNav items in the future) below the breakpoint.
+     *
+     * @example
+     * ```
+     * <AppShell topNav={...} sideNav={...} />
+     * <AppShell mobileNav={{ isOpen, onOpenChange }} />
+     * <AppShell mobileNav={{ hasToggle: false }}>
+     *   <MobileNavToggle />
+     * </AppShell>
+     * <AppShell mobileNav={<MobileNav title="Menu">...</MobileNav>} />
+     * <AppShell mobileNav={false} />
+     * ```
+     */
+    mobileNav?: false | MobileNavConfig | ReactNode;
+    /**
+     * Side navigation — typically an SideNav.
+     *
+     * Pass `undefined` (or omit) when a page has no side navigation.
+     * Do NOT pass a component that renders `null` — AppShell treats any
+     * renderable value as "sidenav exists".
+     *
+     * **Next.js parallel routes:** Conditionally pass the slot based on
+     * the current route rather than relying on a `default.tsx` that
+     * returns `null`:
+     *
+     * @example
+     * ```
+     * const SIDEBAR_ROUTES = ['/dashboard', '/settings'];
+     * function Layout({ children, sidebar }) {
+     *   const hasSidebar = SIDEBAR_ROUTES.some(r => pathname.startsWith(r));
+     *   return (
+     *     <AppShell
+     *       sideNav={hasSidebar ? sidebar : undefined}
+     *       mobileNav={hasSidebar ? { breakpoint: 'md' } : false}>
+     *       {children}
+     *     </AppShell>
+     *   );
+     * }
+     * ```
+     */
+    sideNav?: ReactNode;
+    /**
+     * Top navigation — typically an TopNav.
+     * Same contract as `sideNav` — pass `undefined` when there's no top nav.
+     */
+    topNav?: ReactNode;
+}
+/**
+ * Application-level layout shell. Provides the structural frame for an app:
+ * top navigation, side navigation, and main content area.
+ *
+ * Slot-based API with `topNav`, `sideNav`, `banner`, and `children`.
+ * Supports two height modes (`fill` and `auto`), responsive side nav
+ * collapse, and mobile overlay with backdrop.
+ *
+ * @example
+ * ```
+ * <AppShell
+ *   topNav={<TopNav label="Navigation" heading={<TopNavHeading heading="My App" />} />}
+ *   sideNav={<SideNav>{navSections}</SideNav>}
+ *   mobileNav={
+ *     <MobileNav isOpen={mobileOpen} onOpenChange={(open) => setMobileOpen(open)} title="My App">
+ *       {navSections}
+ *     </MobileNav>
+ *   }>
+ *   <Content />
+ * </AppShell>
+ * ```
+ */
+export declare function AppShell({ variant, banner, children, contentPadding, 'data-testid': dataTestId, height, mobileNav, sideNav, topNav, xstyle, className, style, ref, }: AppShellProps): React.JSX.Element;
+export declare namespace AppShell {
+    var displayName: string;
+}
+//# sourceMappingURL=AppShell.d.ts.map

package/dist/AppShell/AppShell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AppShell.d.ts","sourceRoot":"","sources":["../../src/AppShell/AppShell.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAmBf,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAkC5C;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,MAAM,CAAC;AAE7D;;;;;;;GAOG;AACH;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,EAAE,IAAI,CAAC;IACd,OAAO,EAAE,IAAI,CAAC;IACd,QAAQ,EAAE,IAAI,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,kBAAkB,CAAC;AAEvD;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAEzC;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,CAAC;IAEpB;;;OAGG;IACH,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAEhC;;;;;;;;;OASG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,aAAc,SAAQ,SAAS,CAAC,cAAc,CAAC;IAC9D,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,eAAe,CAAC;IAE1B;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IAEnB;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IAEpB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,WAAW,CAAC;IAE7B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAEzB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,SAAS,CAAC,EAAE,KAAK,GAAG,eAAe,GAAG,SAAS,CAAC;IAEhD;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,OAAO,CAAC,EAAE,SAAS,CAAC;IAEpB;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB;AAkKD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,QAAQ,CAAC,EACvB,OAAoB,EACpB,MAAM,EACN,QAAQ,EACR,cAAc,EACd,aAAa,EAAE,UAAU,EACzB,MAAe,EACf,SAAS,EACT,OAAO,EACP,MAAM,EACN,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,GACJ,EAAE,aAAa,qBA+Wf;yBA7Xe,QAAQ"}