@close-by/clay 0.2.4 → 0.2.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@close-by/clay",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "NiceGUI-like ui.* facade for Clay apps",
   "license": "MIT",
   "type": "module",
@@ -27,10 +27,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@close-by/clay-compiler": "0.2.4",
-    "@close-by/clay-core": "0.2.4",
-    "@close-by/clay-components": "0.2.4",
-    "@close-by/clay-server": "0.2.4",
+    "@close-by/clay-compiler": "0.2.6",
+    "@close-by/clay-core": "0.2.6",
+    "@close-by/clay-components": "0.2.6",
+    "@close-by/clay-server": "0.2.6",
     "@tailwindcss/cli": "^4.3.3",
     "tailwindcss": "^4.3.3"
   }

package/src/index.ts

@@ -9,6 +9,9 @@ import {
   radioGroup as radioGroupFactory,
   combobox as comboboxFactory,
   date as dateFactory,
+  dateRange as dateRangeFactory,
+  timeline as timelineFactory,
+  stepper as stepperFactory,
   tooltip as tooltipFactory,
   avatar as avatarFactory,
   skeleton as skeletonFactory,
@@ -34,6 +37,7 @@ import {
   radialChart as radialChartFactory,
   scatterChart as scatterChartFactory,
   composedChart as composedChartFactory,
+  sparkline as sparklineFactory,
   row as rowFactory,
   column as columnFactory,
   container as containerFactory,
@@ -101,6 +105,14 @@ import {
   type RadioGroupProps,
   type ComboboxProps,
   type DateProps,
+  type DateRangeProps,
+  type DateRangePreset,
+  type TimelineProps,
+  type TimelineItem,
+  type TimelineItemStatus,
+  type StepperProps,
+  type StepperStepOptions,
+  type StepperStepStatus,
   type TooltipProps,
   type AvatarProps,
   type SkeletonProps,
@@ -152,6 +164,11 @@ import {
   type ComposedSeriesType,
   type CartesianChartProps,
   type ChartSeries,
+  type ChartHeadline,
+  type ChartPeriod,
+  type ChartReferenceLine,
+  type ChartReferenceArea,
+  type SparklineProps,
   type CardProps,
   type DialogProps,
   type DialogStackProps,
@@ -318,6 +335,7 @@ import {
   TableBuilder,
   DialogElement,
   DialogStackElement,
+  StepperElement,
   AlertDialogElement,
   DropdownMenuElement,
   ContextMenuElement,
@@ -446,6 +464,14 @@ export type {
   DialogProps,
   DialogStackProps,
   DialogStackStepOptions,
+  StepperProps,
+  StepperStepOptions,
+  StepperStepStatus,
+  TimelineProps,
+  TimelineItem,
+  TimelineItemStatus,
+  DateRangeProps,
+  DateRangePreset,
   AlertDialogProps,
   DropdownMenuProps,
   DropdownItemOptions,
@@ -600,6 +626,7 @@ export {
   TableBuilder,
   DialogElement,
   DialogStackElement,
+  StepperElement,
   AlertDialogElement,
   DropdownMenuElement,
   SheetElement,
@@ -680,6 +707,29 @@ export function date(props?: DateProps): Element {
   return dateFactory(props);
 }
 
+/** Date range picker with presets. Prefer `ui.dateRange`. See {@link DateRangeProps}. */
+export function dateRange(props?: DateRangeProps): Element {
+  return dateRangeFactory(props);
+}
+
+/** Chronological events for feeds and deploy logs. See {@link TimelineProps}. */
+export function timeline(props: TimelineProps): Element {
+  return timelineFactory(props);
+}
+
+/** Inline multi-step flow with step panels. See {@link StepperProps}. */
+export function stepper(
+  fn: (s: StepperElement) => void,
+  props?: StepperProps,
+): StepperElement;
+export function stepper(
+  props: StepperProps,
+  fn: (s: StepperElement) => void,
+): StepperElement;
+export function stepper(a: any, b?: any): StepperElement {
+  return stepperFactory(a, b);
+}
+
 /** Tooltip around content (`fn` or props-first). Prefer `ui.tooltip`. See {@link TooltipProps}. */
 export function tooltip(fn: () => void, props: TooltipProps): Element;
 export function tooltip(props: TooltipProps, fn: () => void): Element;
@@ -970,6 +1020,11 @@ export function composedChart(props: ComposedChartProps): Element {
   return composedChartFactory(props);
 }
 
+/** KPI card with inline sparkline. Prefer `ui.sparkline`. See {@link SparklineProps}. */
+export function sparkline(props: SparklineProps): Element {
+  return sparklineFactory(props);
+}
+
 /** Horizontal flex row (`fn` or props-first). Prefer `ui.row`. */
 export function row(fn: () => void, props?: Parameters<typeof rowFactory>[1]): Element;
 export function row(props: Parameters<typeof rowFactory>[0], fn: () => void): Element;
@@ -1522,6 +1577,9 @@ export const ui = {
   radioGroup,
   combobox,
   date,
+  dateRange,
+  timeline,
+  stepper,
   tooltip,
   avatar,
   skeleton,
@@ -1568,6 +1626,7 @@ export const ui = {
   radialChart,
   scatterChart,
   composedChart,
+  sparkline,
   row,
   column,
   container,

package/src/pages.ts

@@ -58,6 +58,10 @@ export type PageMeta = {
    * UX only — still call `requireRole` in the page builder.
    */
   roles?: string[];
+  /** Nest this page under a collapsible sidebar group with the given label. */
+  group?: string;
+  /** Lucide icon for the group parent row (first page in the group with this set wins). */
+  groupIcon?: string;
 };
 
 const pageMetaByPath = new Map<string, PageMeta>();
@@ -140,8 +144,76 @@ export type NavFromPagesOptions = {
   role?: string;
   /** Viewer roles — page is shown if it has no `roles` meta, or any overlap. */
   roles?: string[];
+  /**
+   * When true, nest `/examples/*` routes (except `/examples/auth`) under an
+   * "Examples" group. Individual pages can override with `pageMeta.group`.
+   */
+  groupExamples?: boolean;
+  /** Label for the auto examples group. Default `"Examples"`. */
+  groupExamplesLabel?: string;
+  /** Icon for the auto examples group. Default `"layout-grid"`. */
+  groupExamplesIcon?: string;
 };
 
+type RankedNavPage = {
+  href: string;
+  label: string;
+  icon: string;
+  order: number;
+  group?: string;
+  groupIcon?: string;
+};
+
+function resolvePageGroup(
+  href: string,
+  meta: PageMeta,
+  opts?: NavFromPagesOptions,
+): { group?: string; groupIcon?: string } {
+  if (meta.group !== undefined) {
+    return meta.group ? { group: meta.group, groupIcon: meta.groupIcon } : {};
+  }
+  if (opts?.groupExamples && href.startsWith('/examples/') && href !== '/examples/auth') {
+    return {
+      group: opts.groupExamplesLabel ?? 'Examples',
+      groupIcon: opts.groupExamplesIcon ?? 'layout-grid',
+    };
+  }
+  return {};
+}
+
+function buildNavFromRanked(ranked: RankedNavPage[]): AppNavItem[] {
+  const top: Array<{ order: number; node: AppNavItem }> = [];
+  const groups = new Map<string, AppNavItem>();
+
+  for (const row of ranked) {
+    const leaf: AppNavItem = { label: row.label, href: row.href, icon: row.icon };
+    if (!row.group) {
+      top.push({ order: row.order, node: leaf });
+      continue;
+    }
+
+    let parent = groups.get(row.group);
+    if (!parent) {
+      parent = {
+        label: row.group,
+        href: row.href,
+        icon: row.groupIcon ?? 'folder',
+        items: [],
+      };
+      groups.set(row.group, parent);
+      top.push({ order: row.order, node: parent });
+    } else {
+      const entry = top.find((t) => t.node === parent);
+      if (entry) entry.order = Math.min(entry.order, row.order);
+      if (row.groupIcon && parent.icon === 'folder') parent.icon = row.groupIcon;
+    }
+    parent.items!.push(leaf);
+  }
+
+  top.sort((a, b) => a.order - b.order || a.node.label.localeCompare(b.node.label));
+  return top.map((t) => t.node);
+}
+
 /**
  * Build primary sidebar nav from registered pages + collected `pageMeta`.
  * Filters by `nav: false` and optional role overlap; sorts by `order` then path.
@@ -160,10 +232,11 @@ export function navFromPages(opts?: NavFromPagesOptions): AppNavItem[] {
   }
 
   const paths = getRegisteredPaths();
-  const ranked = paths
+  const ranked: RankedNavPage[] = paths
     .map((href) => {
       const meta = pageMetaByPath.get(href) ?? {};
       const order = href === '/' ? 0 : (meta.order ?? 100);
+      const { group, groupIcon } = resolvePageGroup(href, meta, opts);
       return {
         href,
         label: meta.label ?? labelFromPath(href),
@@ -171,6 +244,8 @@ export function navFromPages(opts?: NavFromPagesOptions): AppNavItem[] {
         order,
         nav: meta.nav !== false,
         roles: meta.roles,
+        group,
+        groupIcon,
       };
     })
     .filter((item) => {
@@ -178,9 +253,10 @@ export function navFromPages(opts?: NavFromPagesOptions): AppNavItem[] {
       if (!item.roles || item.roles.length === 0) return true;
       if (viewer.size === 0) return false;
       return item.roles.some((r) => viewer.has(r));
-    });
+    })
+    .map(({ nav: _nav, roles: _roles, ...rest }) => rest);
   ranked.sort((a, b) => a.order - b.order || a.href.localeCompare(b.href));
-  return ranked.map(({ href, label, icon }) => ({ href, label, icon }));
+  return buildNavFromRanked(ranked);
 }
 
 /** Test helper: clear page registry + meta map. */