@matteoaliano/forest-ui 1.0.0 → 1.1.0

package/bin/sync.mjs

@@ -3,94 +3,59 @@
 /**
  * forest-ui sync
  *
- * Copies skill folders into the consuming project's .claude/skills/
- * directory so Claude Code automatically discovers Forest UI preset rules.
+ * DEPRECATED for consumers — documentation + enforcement now ship as a Claude
+ * Code plugin. Copying loose skill files is no longer supported because stale
+ * copies drift from the plugin's hook.
+ *
+ * `--internal` (used by the monorepo's `npm run sync`) still propagates the
+ * skill source to the dogfood `.claude/skills/` copy and the plugin bundle.
  */
 
-import { readFileSync, mkdirSync, existsSync, readdirSync, cpSync, rmSync } from "node:fs";
+import { mkdirSync, readdirSync, cpSync } from "node:fs";
 import { resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const skillsDir = resolve(__dirname, "..", "skills");
 
-// Find the consuming project root (walk up until we find package.json)
-function findProjectRoot(startDir) {
-    let dir = startDir;
-    while (dir !== dirname(dir)) {
-        if (existsSync(resolve(dir, "package.json"))) {
-            try {
-                const pkg = JSON.parse(readFileSync(resolve(dir, "package.json"), "utf-8"));
-                if (pkg.name !== "@matteoaliano/forest-ui") return dir;
-            } catch {
-                return dir;
-            }
-        }
-        dir = dirname(dir);
-    }
-    return process.cwd();
-}
-
-const projectRoot = findProjectRoot(process.cwd());
+if (!process.argv.includes("--internal")) {
+  console.log(`
+🌲 Forest UI — \`sync\` is deprecated
 
-console.log(`\n🌲 Forest UI — Syncing skills\n`);
-console.log(`   Project root: ${projectRoot}\n`);
+   Skills are now delivered through the Forest Design System Claude Code
+   plugin, which also ships design-system enforcement hooks. Install it:
 
-// Clean up legacy guideline files from pre-v0.4.1
-const legacyPaths = [
-    resolve(projectRoot, ".claude", "forest-ui.md"),
-    resolve(projectRoot, ".cursor", "rules", "forest-ui.mdc"),
-    resolve(projectRoot, ".gemini", "forest-ui.md"),
-    resolve(projectRoot, ".antigravity", "rules.md"),
-];
+     /plugin marketplace add Witailer/wtl-design-system-forest
+     /plugin install forest-ui@forest-design-system
 
-let cleaned = 0;
-for (const legacyPath of legacyPaths) {
-    if (existsSync(legacyPath)) {
-        try {
-            rmSync(legacyPath);
-            const rel = legacyPath.replace(projectRoot + "/", "");
-            console.log(`   🧹 Removed legacy ${rel}`);
-            cleaned++;
-        } catch (err) {
-            const rel = legacyPath.replace(projectRoot + "/", "");
-            console.log(`   ⚠️  Could not remove ${rel} (${err.message})`);
-        }
-    }
+   No files were copied. If you previously synced, you can delete
+   .claude/skills/forest-alkemy-plus/ — the plugin replaces it.
+`);
+  process.exit(0);
 }
-if (cleaned > 0) console.log();
 
-let synced = 0;
-let total = 0;
+// ── Internal monorepo sync: skills/ → dogfood + plugin bundle ──
+const repoRoot = resolve(__dirname, "..", "..", "..");
+const targets = [
+  resolve(repoRoot, ".claude", "skills"),
+  resolve(repoRoot, "plugins", "forest-ui", "skills"),
+];
 
-if (!existsSync(skillsDir)) {
-    console.log(`   ⚠️  No skills directory found, nothing to sync.\n`);
-    process.exit(0);
-}
+console.log(`\n🌲 Forest UI — Syncing skills (internal)\n`);
 
 const skillFolders = readdirSync(skillsDir, { withFileTypes: true })
-    .filter((d) => d.isDirectory())
-    .map((d) => d.name);
-
-if (skillFolders.length === 0) {
-    console.log(`   ⚠️  No skill folders found, nothing to sync.\n`);
-    process.exit(0);
-}
+  .filter((d) => d.isDirectory())
+  .map((d) => d.name);
 
-const claudeSkillsDir = resolve(projectRoot, ".claude", "skills");
-
-for (const folder of skillFolders) {
-    const src = resolve(skillsDir, folder);
-    const dest = resolve(claudeSkillsDir, folder);
-    total++;
-    try {
-        mkdirSync(dest, { recursive: true });
-        cpSync(src, dest, { recursive: true });
-        console.log(`   ✅ .claude/skills/${folder}/`);
-        synced++;
-    } catch (err) {
-        console.log(`   ⚠️  .claude/skills/${folder}/ skipped (${err.message})`);
-    }
+let synced = 0;
+for (const target of targets) {
+  for (const folder of skillFolders) {
+    const dest = resolve(target, folder);
+    mkdirSync(dest, { recursive: true });
+    cpSync(resolve(skillsDir, folder), dest, { recursive: true });
+    console.log(`   ✅ ${dest.replace(repoRoot + "/", "")}/`);
+    synced++;
+  }
 }
 
-console.log(`\n   Synced ${synced}/${total} skills.\n`);
+console.log(`\n   Synced ${skillFolders.length} skill(s) to ${targets.length} target(s) (${synced} copies).\n`);

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { Theme } from '@mui/material/styles';
+import { Theme, SxProps } from '@mui/material/styles';
 export { useColorScheme } from '@mui/material/styles';
 import * as _mui_material from '@mui/material';
 import { BoxProps } from '@mui/material';
@@ -369,6 +369,78 @@ interface SidebarItemProps extends ListItemButtonProps {
 }
 declare function SidebarItem({ icon, label, endAdornment, sx, ...rest }: SidebarItemProps): react_jsx_runtime.JSX.Element;
 
+interface AppShellNavItem {
+    label: string;
+    icon: React__default.ReactNode;
+    active?: boolean;
+    href?: string;
+    onClick?: () => void;
+    /** Router escape — e.g. Next.js Link or React Router Link. */
+    component?: React__default.ElementType;
+    /** Rendered after the label when expanded (e.g. a count Chip). */
+    endAdornment?: React__default.ReactNode;
+}
+interface AppShellProps {
+    /** Data-driven sidebar nav. */
+    navItems?: AppShellNavItem[];
+    /** Escape hatch: full control over sidebar content. Overrides navItems. */
+    nav?: React__default.ReactNode;
+    /** Product brand passed to <Logo>. Default "studio". */
+    product?: LogoProduct;
+    /** Logomark (default) or the full wordmark logo. */
+    logoVariant?: "logomark" | "full";
+    /** Escape hatch: fully custom brand node (overrides product/logoVariant). */
+    brand?: React__default.ReactNode;
+    /** Center search: true → default <Search>; node → custom; omit → none. */
+    search?: React__default.ReactNode | boolean;
+    /** Right-side AppBar actions. The mandatory color-mode toggle is rendered
+     *  by AppShell itself, before these. */
+    actions?: React__default.ReactNode;
+    sidebarBehavior?: "permanent" | "hover";
+    defaultSidebarOpen?: boolean;
+    /** The page content — expected to be a <Page>. */
+    children: React__default.ReactNode;
+}
+/**
+ * The mandatory top-level layout for authenticated Forest UI surfaces: a
+ * sticky AppBar (brand / search / actions + the color-mode toggle) over a
+ * SidebarNav and a main content area. Render a <Page> as children.
+ *
+ * Below the "sm" breakpoint the sidebar becomes a temporary overlay drawer
+ * opened by a hamburger button in the AppBar.
+ */
+declare function AppShell({ navItems, nav, product, logoVariant, brand, search, actions, sidebarBehavior, defaultSidebarOpen, children, }: AppShellProps): react_jsx_runtime.JSX.Element;
+
+interface PageBreadcrumb {
+    label: string;
+    href?: string;
+    onClick?: () => void;
+    /** Router escape — e.g. Next.js Link or React Router Link. */
+    component?: React__default.ElementType;
+}
+interface PageProps {
+    /** Page title. Rendered as Typography variant="h5". */
+    title: string;
+    /** Breadcrumb trail rendered above the title. Omit for pages without one. */
+    breadcrumbs?: PageBreadcrumb[];
+    /** Right-aligned header actions (e.g. a primary Button). */
+    actions?: React__default.ReactNode;
+    /** Drop the default 24px gutters for full-bleed pages. */
+    disableGutters?: boolean;
+    /** Constrain and center the content column. Default: full width. */
+    maxWidth?: number | string;
+    sx?: SxProps<Theme>;
+    children?: React__default.ReactNode;
+}
+/**
+ * The mandatory page-content scaffold rendered inside the App Shell's main
+ * slot. Owns the flat `background.paper` surface and the standard gutters, and
+ * renders the page header (breadcrumbs → title + actions). Everything below
+ * the header goes in `children` — widgets, charts, and tables belong inside
+ * `<Card>`s there.
+ */
+declare function Page({ title, breadcrumbs, actions, disableGutters, maxWidth, sx, children, }: PageProps): react_jsx_runtime.JSX.Element;
+
 declare const Box: _mui_types.OverridableComponent<_mui_system.BoxTypeMap<{}, "div", _mui_material.Theme>>;
 
 declare const Stack: _mui_material_OverridableComponent.OverridableComponent<_mui_material.StackTypeMap<{}, "div">>;
@@ -408,4 +480,4 @@ declare function ScatterChart({ series, colors, ...props }: ScatterChartProps):
 type GaugeProps = GaugeProps$1;
 declare function Gauge(props: GaugeProps): react_jsx_runtime.JSX.Element;
 
-export { AppBarNavItem, type AppBarNavItemProps, BarChart, type BarChartProps, Box, Button, ButtonGroup, type ButtonProps, Card, type CardProps, Chip, Container, DatePicker, type DatePickerProps, Drawer, Fab, type ForestCardColor, type ForestChipColor, type ForestChipProps, ForestProvider, type ForestProviderProps, Gauge, Grid, IconButton, type IconButtonProps, type IconButtonVariant, LineChart, type LineChartProps, Logo, type LogoProps, MultiSelect, type MultiSelectOption, type MultiSelectProps, Paper, PieChart, type PieChartProps, Popover, Portal, ScatterChart, Search, type SearchProps, Select, SidebarItem, type SidebarItemProps, SidebarNav, type SidebarNavProps, Stack, Switch, Tooltip, useChartColors, useSidebar };
+export { AppBarNavItem, type AppBarNavItemProps, AppShell, type AppShellNavItem, type AppShellProps, BarChart, type BarChartProps, Box, Button, ButtonGroup, type ButtonProps, Card, type CardProps, Chip, Container, DatePicker, type DatePickerProps, Drawer, Fab, type ForestCardColor, type ForestChipColor, type ForestChipProps, ForestProvider, type ForestProviderProps, Gauge, Grid, IconButton, type IconButtonProps, type IconButtonVariant, LineChart, type LineChartProps, Logo, type LogoProps, MultiSelect, type MultiSelectOption, type MultiSelectProps, Page, type PageBreadcrumb, type PageProps, Paper, PieChart, type PieChartProps, Popover, Portal, ScatterChart, Search, type SearchProps, Select, SidebarItem, type SidebarItemProps, SidebarNav, type SidebarNavProps, Stack, Switch, Tooltip, useChartColors, useSidebar };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { Theme } from '@mui/material/styles';
+import { Theme, SxProps } from '@mui/material/styles';
 export { useColorScheme } from '@mui/material/styles';
 import * as _mui_material from '@mui/material';
 import { BoxProps } from '@mui/material';
@@ -369,6 +369,78 @@ interface SidebarItemProps extends ListItemButtonProps {
 }
 declare function SidebarItem({ icon, label, endAdornment, sx, ...rest }: SidebarItemProps): react_jsx_runtime.JSX.Element;
 
+interface AppShellNavItem {
+    label: string;
+    icon: React__default.ReactNode;
+    active?: boolean;
+    href?: string;
+    onClick?: () => void;
+    /** Router escape — e.g. Next.js Link or React Router Link. */
+    component?: React__default.ElementType;
+    /** Rendered after the label when expanded (e.g. a count Chip). */
+    endAdornment?: React__default.ReactNode;
+}
+interface AppShellProps {
+    /** Data-driven sidebar nav. */
+    navItems?: AppShellNavItem[];
+    /** Escape hatch: full control over sidebar content. Overrides navItems. */
+    nav?: React__default.ReactNode;
+    /** Product brand passed to <Logo>. Default "studio". */
+    product?: LogoProduct;
+    /** Logomark (default) or the full wordmark logo. */
+    logoVariant?: "logomark" | "full";
+    /** Escape hatch: fully custom brand node (overrides product/logoVariant). */
+    brand?: React__default.ReactNode;
+    /** Center search: true → default <Search>; node → custom; omit → none. */
+    search?: React__default.ReactNode | boolean;
+    /** Right-side AppBar actions. The mandatory color-mode toggle is rendered
+     *  by AppShell itself, before these. */
+    actions?: React__default.ReactNode;
+    sidebarBehavior?: "permanent" | "hover";
+    defaultSidebarOpen?: boolean;
+    /** The page content — expected to be a <Page>. */
+    children: React__default.ReactNode;
+}
+/**
+ * The mandatory top-level layout for authenticated Forest UI surfaces: a
+ * sticky AppBar (brand / search / actions + the color-mode toggle) over a
+ * SidebarNav and a main content area. Render a <Page> as children.
+ *
+ * Below the "sm" breakpoint the sidebar becomes a temporary overlay drawer
+ * opened by a hamburger button in the AppBar.
+ */
+declare function AppShell({ navItems, nav, product, logoVariant, brand, search, actions, sidebarBehavior, defaultSidebarOpen, children, }: AppShellProps): react_jsx_runtime.JSX.Element;
+
+interface PageBreadcrumb {
+    label: string;
+    href?: string;
+    onClick?: () => void;
+    /** Router escape — e.g. Next.js Link or React Router Link. */
+    component?: React__default.ElementType;
+}
+interface PageProps {
+    /** Page title. Rendered as Typography variant="h5". */
+    title: string;
+    /** Breadcrumb trail rendered above the title. Omit for pages without one. */
+    breadcrumbs?: PageBreadcrumb[];
+    /** Right-aligned header actions (e.g. a primary Button). */
+    actions?: React__default.ReactNode;
+    /** Drop the default 24px gutters for full-bleed pages. */
+    disableGutters?: boolean;
+    /** Constrain and center the content column. Default: full width. */
+    maxWidth?: number | string;
+    sx?: SxProps<Theme>;
+    children?: React__default.ReactNode;
+}
+/**
+ * The mandatory page-content scaffold rendered inside the App Shell's main
+ * slot. Owns the flat `background.paper` surface and the standard gutters, and
+ * renders the page header (breadcrumbs → title + actions). Everything below
+ * the header goes in `children` — widgets, charts, and tables belong inside
+ * `<Card>`s there.
+ */
+declare function Page({ title, breadcrumbs, actions, disableGutters, maxWidth, sx, children, }: PageProps): react_jsx_runtime.JSX.Element;
+
 declare const Box: _mui_types.OverridableComponent<_mui_system.BoxTypeMap<{}, "div", _mui_material.Theme>>;
 
 declare const Stack: _mui_material_OverridableComponent.OverridableComponent<_mui_material.StackTypeMap<{}, "div">>;
@@ -408,4 +480,4 @@ declare function ScatterChart({ series, colors, ...props }: ScatterChartProps):
 type GaugeProps = GaugeProps$1;
 declare function Gauge(props: GaugeProps): react_jsx_runtime.JSX.Element;
 
-export { AppBarNavItem, type AppBarNavItemProps, BarChart, type BarChartProps, Box, Button, ButtonGroup, type ButtonProps, Card, type CardProps, Chip, Container, DatePicker, type DatePickerProps, Drawer, Fab, type ForestCardColor, type ForestChipColor, type ForestChipProps, ForestProvider, type ForestProviderProps, Gauge, Grid, IconButton, type IconButtonProps, type IconButtonVariant, LineChart, type LineChartProps, Logo, type LogoProps, MultiSelect, type MultiSelectOption, type MultiSelectProps, Paper, PieChart, type PieChartProps, Popover, Portal, ScatterChart, Search, type SearchProps, Select, SidebarItem, type SidebarItemProps, SidebarNav, type SidebarNavProps, Stack, Switch, Tooltip, useChartColors, useSidebar };
+export { AppBarNavItem, type AppBarNavItemProps, AppShell, type AppShellNavItem, type AppShellProps, BarChart, type BarChartProps, Box, Button, ButtonGroup, type ButtonProps, Card, type CardProps, Chip, Container, DatePicker, type DatePickerProps, Drawer, Fab, type ForestCardColor, type ForestChipColor, type ForestChipProps, ForestProvider, type ForestProviderProps, Gauge, Grid, IconButton, type IconButtonProps, type IconButtonVariant, LineChart, type LineChartProps, Logo, type LogoProps, MultiSelect, type MultiSelectOption, type MultiSelectProps, Page, type PageBreadcrumb, type PageProps, Paper, PieChart, type PieChartProps, Popover, Portal, ScatterChart, Search, type SearchProps, Select, SidebarItem, type SidebarItemProps, SidebarNav, type SidebarNavProps, Stack, Switch, Tooltip, useChartColors, useSidebar };