@optimum-intelligence/opti-ui 0.4.0 → 0.5.0

package/README.md

@@ -72,24 +72,26 @@ so the components work in Next.js App Router.
 
 | Area | Components |
 | --- | --- |
-| Layout | `AppShell`, `Navbar` (+ `NavbarHeader/Brand/Section/SectionLabel/Item/Footer`), `PageHeader`, `Grid`, `Stack`, `Card` (+ parts), `StatCard`, `Separator`, `ScrollArea` |
+| Layout | `AppShell`, `Navbar` (+ `NavbarHeader/Brand/Section/SectionLabel/Item/Group/Footer`), `PageHeader`, `Grid`, `Stack`, `Card` (+ parts), `StatCard`, `Separator`, `ScrollArea` |
 | Actions | `Button`, `IconButton`, `Toggle`, `ToggleGroup`, `SegmentedControl`, `Menu.*`, `ContextMenu.*`, `Toolbar.*` |
 | Forms | `Field.*`, `Fieldset.*`, `Form`, `Input`, `TextField`, `PasswordInput`, `PasswordField`, `Textarea`, `TextareaField`, `Select` (+ parts), `Combobox` (+ parts), `Checkbox`, `CheckboxGroup`, `Radio`, `RadioGroup`, `Switch`, `NumberField`, `Slider`, `SearchInput`, `DatePicker`, `DateTimePicker`, `DateRangePicker`, `Calendar`, `RangeCalendar`, `FileUpload`, `Dropzone`, `FileItem` |
 | Overlays | `Dialog.*` (modal, or a sheet with `placement`), `AlertDialog.*`, `Drawer` (detail side panel), `Popover.*`, `PreviewCard.*`, `Tooltip`, `ToastProvider` + `useToast()`, `CommandPalette` |
 | Disclosure & navigation | `Tabs.*`, `Accordion.*`, `Collapsible.*`, `Breadcrumbs` + `Breadcrumb`, `Pagination`, `Stepper` |
 | Feedback & data | `Alert`, `Badge`, `Tag`, `Avatar`, `AvatarGroup`, `Progress`, `Meter`, `Skeleton`, `SkeletonText`, `Spinner`, `Table` (+ parts), `DataTable`, `EmptyState`, `Heading`, `Text`, `Eyebrow`, `Link` |
-| Theme | `ThemeProvider`, `createTheme`, `themeToStyle`, icons (`CheckIcon`, `ChevronDownIcon`, …) |
+| Theme | `ThemeProvider`, `createTheme`, `themeToStyle`, `DateConfigProvider`, `useDateConfig`, icons (`CheckIcon`, `ChevronDownIcon`, …) |
 
 Components with a common one-line form can be called directly, and their parts are attached for full
 control: `<Select items={…} />` or `<Select.Root>…<Select.Trigger/>…</Select.Root>`; the same applies to
 `Combobox` and `Tooltip`. Compound components (`Dialog`, `Menu`, `Tabs`, …) mirror Base UI's part names,
 so the [Base UI docs](https://base-ui.com/react/overview/quick-start) apply to them directly.
 
-`DatePicker` and `DateTimePicker` use ISO strings as values (`"2026-03-09"`, `"2026-03-09T14:30"`), the
-same format as native date inputs; `DateRangePicker` uses `{ start, end }` with both days inclusive.
-Dates are displayed the same way in every locale, on a 24-hour clock: `2026-03-09 14:30:00` in fields
-(`formatDate`) and `2026. March 9. 14:30` where they are written out (`formatDateLong`); the locale only
-translates month and weekday names.
+Calendar dates are plain ISO strings (`"2026-03-09"`), the same format as native date inputs;
+`DateRangePicker` uses `{ start, end }` with both days inclusive. Date-times are UTC instants
+(`"2026-03-09T13:30:00Z"`), shown and edited in `timeZone` (the browser's by default) and converted back on
+commit. `granularity` (`year` … `second`) picks the grid or time fields and cuts the value to that unit.
+Display is ISO-style on a 24-hour clock (`2026-03-09 14:30`) unless you pass a `format` pattern
+(`"DD.MM.YYYY"`, `"MMMM YYYY"`). `formatDate` formats values the same way outside the pickers, and
+`DateConfigProvider` sets app-wide defaults for locale, time zone, week start and formats.
 
 `DataTable` handles search, filters, sorting, pagination, selection, row actions and inline editing for
 rows held in memory. Columns declare what they take part in:

package/dist/components/app-shell/AppShell.d.ts

@@ -59,18 +59,60 @@ export type NavbarItemState = {
     active: boolean;
 };
 export interface NavbarItemProps extends useRender.ComponentProps<'a', NavbarItemState> {
-    /** Icon shown before the label; it stays visible when the navbar is collapsed to a rail. */
+    /** Icon shown before the label; it stays visible when the navbar is collapsed to a rail. Not shown inside a `NavbarGroup`. */
     icon?: React.ReactNode;
-    /** Marks the current page (sets aria-current). */
+    /** Marks the current page (sets aria-current). Also opens the surrounding `NavbarGroup`. */
     active?: boolean;
     /** Trailing content such as a count badge. */
     badge?: React.ReactNode;
+    /**
+     * Also shows the item in the `AppShell` mobile tab bar (icon and label). Pin up to four items; the
+     * first four in navbar order are used. Has no effect outside an `AppShell`.
+     */
+    pinned?: boolean;
 }
 /**
  * Navigation link. Renders an `<a>`; use `render={<Link to="…" />}` for a
- * router link or `render={<button />}` for an action.
+ * router link or `render={<button />}` for an action. Inside a `NavbarGroup` it becomes an indented sub-link.
  */
-export declare function NavbarItem({ icon, active, badge, render, children, ref, ...props }: NavbarItemProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
+export declare function NavbarItem({ icon, active, badge, pinned, render, children, ref, ...props }: NavbarItemProps): React.ReactElement<unknown, string | React.JSXElementConstructor<any>>;
+export interface NavbarGroupProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'title'> {
+    /** Ref to the group's root element. */
+    ref?: React.Ref<HTMLDivElement>;
+    /** Text of the parent row. A string also becomes its tooltip on the collapsed rail. */
+    label: React.ReactNode;
+    /** Icon of the parent row; it stays visible when the navbar is collapsed to a rail. */
+    icon?: React.ReactNode;
+    /** Trailing content of the parent row, such as a count badge. */
+    badge?: React.ReactNode;
+    /** Controlled open state. Takes over from the automatic opening on an active child. */
+    open?: boolean;
+    /**
+     * Initial open state when uncontrolled. Whenever a child item becomes `active`, the group opens.
+     * @default true when a child item is active
+     */
+    defaultOpen?: boolean;
+    /** Called when the user opens or closes the group. */
+    onOpenChange?: (open: boolean) => void;
+    /** Sub-links: `NavbarItem` elements (directly or in fragments), shown indented and without icons. */
+    children?: React.ReactNode;
+}
+/**
+ * Expandable parent row in a `Navbar` with nested `NavbarItem` sub-links. Place it in a `NavbarSection`
+ * next to other items. On a collapsed rail the sub-links are hidden and the parent shows as active when
+ * one of them is; the hover peek shows the full tree.
+ *
+ * @example
+ * <NavbarSection>
+ *   <NavbarGroup icon={<Truck />} label="Fleet">
+ *     <NavbarItem href="/fleet/vehicles" active>Vehicles</NavbarItem>
+ *     <NavbarItem href="/fleet/drivers">Drivers</NavbarItem>
+ *   </NavbarGroup>
+ * </NavbarSection>
+ */
+export declare function NavbarGroup({ label, icon, badge, open: openProp, defaultOpen, onOpenChange, className, children, ref, ...props }: NavbarGroupProps): React.JSX.Element;
+export type MobileNavPosition = 'bottom' | 'top';
+export type MoreTabPosition = 'start' | 'end';
 export interface AppShellProps extends React.HTMLAttributes<HTMLDivElement> {
     /** Ref to the shell's root element. */
     ref?: React.Ref<HTMLDivElement>;
@@ -80,17 +122,44 @@ export interface AppShellProps extends React.HTMLAttributes<HTMLDivElement> {
     mobileBrand?: React.ReactNode;
     /** Extra content on the right of the mobile top bar. */
     mobileActions?: React.ReactNode;
+    /**
+     * Where small screens show the tab bar of pinned `NavbarItem`s: below or above the main area. Both look
+     * the same; the "More" slot (see `moreTabPosition`) opens the navbar drawer. The top bar with `mobileBrand` and
+     * `mobileActions` only appears when one of them is set. Without pinned items, a top bar with a menu
+     * button is shown instead.
+     */
+    mobileNavPosition?: MobileNavPosition;
     /** Accessible name of the button that opens the navigation drawer on small screens. */
     menuLabel?: string;
+    /** Label of the tab-bar slot that opens the navigation drawer. */
+    moreLabel?: string;
+    /** Whether the "More" slot comes before or after the pinned items in the tab bar. */
+    moreTabPosition?: MoreTabPosition;
     /** Props for the scrolling `<main>` element. */
     mainProps?: React.HTMLAttributes<HTMLElement>;
 }
 /**
  * Full-height layout with a fixed navbar and an internally scrolling main
- * area. Below 900px the navbar moves into a slide-in drawer.
+ * area. Below 900px the navbar moves into a slide-in drawer, and `NavbarItem`s marked `pinned` show in a
+ * tab bar (see `mobileNavPosition`).
  * Customize width with `--oui-navbar-width` and `--oui-navbar-collapsed-width`.
+ *
+ * @example
+ * <AppShell
+ *   mobileBrand="OptiControl"
+ *   navbar={
+ *     <Navbar>
+ *       <NavbarSection>
+ *         <NavbarItem href="/" icon={<Home />} active pinned>Overview</NavbarItem>
+ *         <NavbarItem href="/fleet" icon={<Truck />} pinned>Fleet</NavbarItem>
+ *       </NavbarSection>
+ *     </Navbar>
+ *   }
+ * >
+ *   <PageHeader title="Overview" />
+ * </AppShell>
  */
-export declare function AppShell({ navbar, mobileBrand, mobileActions, menuLabel, mainProps, className, children, ref, ...props }: AppShellProps): React.JSX.Element;
+export declare function AppShell({ navbar, mobileBrand, mobileActions, mobileNavPosition, menuLabel, moreLabel, moreTabPosition, mainProps, className, children, ref, ...props }: AppShellProps): React.JSX.Element;
 export interface PageHeaderProps extends Omit<React.HTMLAttributes<HTMLElement>, 'title'> {
     /** Ref to the `<header>` element. */
     ref?: React.Ref<HTMLElement>;