@misoto22/design 0.7.0 → 0.9.0

package/dist/components/Sidebar/Sidebar.d.ts

@@ -0,0 +1,349 @@
+import * as react from 'react';
+import { ComponentProps, ReactNode } from 'react';
+import { LucideIcon } from 'lucide-react';
+import { NavItemProps } from '../NavItem/NavItem.js';
+
+/** What happens to the rail when it is closed. See {@link SidebarProviderProps.collapsible}. */
+type SidebarCollapsible = 'icon' | 'offcanvas' | 'none';
+/** Which edge of the layout the rail is on. Logical, so it follows `dir`. */
+type SidebarSide = 'start' | 'end';
+/** How the rail meets the page. See {@link SidebarProviderProps.variant}. */
+type SidebarVariant = 'flush' | 'inset' | 'floating';
+/** Where the rail stops being a column. See {@link SidebarProviderProps.breakpoint}. */
+type SidebarBreakpoint = 'sm' | 'md' | 'lg' | 'xl';
+interface SidebarState {
+    /** Whether the rail is showing — the docked column, or the open drawer. */
+    open: boolean;
+    setOpen: (open: boolean) => void;
+    toggle: () => void;
+    collapsible: SidebarCollapsible;
+    /** True only in the state where labels are hidden and rows are icons. */
+    iconOnly: boolean;
+    side: SidebarSide;
+    variant: SidebarVariant;
+    /**
+     * True while the viewport is under the provider's breakpoint, where the rail
+     * is a drawer over the page rather than a column beside it.
+     */
+    mobile: boolean;
+    /** The drawer covers its positioned ancestor rather than the window. */
+    contained: boolean;
+    /** The step below which the rail is a drawer, or `null` for never. */
+    breakpoint: SidebarBreakpoint | null;
+}
+/**
+ * The rail's own state, for anything that has to answer to it.
+ *
+ * A page beside the rail needs it to reserve the right width; a control inside
+ * needs to know whether its label is being drawn.
+ *
+ * This one THROWS outside a provider, and the parts above do not, and the
+ * difference is who made the mistake. A part rendered on its own is somebody
+ * writing `<Sidebar>` to see what it looks like; a call to this hook is code
+ * asking for state that nothing is keeping, and returning a plausible default
+ * there is a layout that is wrong in one state and right in the other with
+ * nothing to say which.
+ */
+declare function useSidebar(): SidebarState;
+interface SidebarProviderProps {
+    /** Controlled open state. Leave off to let the provider own it. */
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** What closing does to the rail. See {@link SidebarProps.collapsible}. */
+    collapsible?: SidebarCollapsible;
+    /**
+     * The keyboard shortcut that toggles the rail, as a single letter.
+     *
+     * `b`, with the platform's own modifier, because that is what every editor
+     * and every application shell already uses for the same thing. Pass `null`
+     * to bind nothing — an app that already owns that chord should not have it
+     * taken twice, and a rail that cannot be closed does not need a shortcut for
+     * closing it.
+     */
+    shortcut?: string | null;
+    /** Which edge the rail is on. Logical: `end` is the right in LTR, the left in RTL. */
+    side?: SidebarSide;
+    /**
+     * How the rail meets the page.
+     *
+     * `flush` is a column with a hairline down its inner edge — the rail and the
+     * page are one surface divided by a line. `floating` lifts the rail off that
+     * surface as its own bordered panel with the page ground showing around it.
+     * `inset` is the same gesture the other way up: the rail sits on the page
+     * ground and `SidebarInset` draws the CONTENT as the panel.
+     *
+     * `floating` and `inset` both need a ground to sit on — put `bg-(--stone)` on
+     * the element holding the provider, or they are a panel on the same colour as
+     * the thing behind it.
+     */
+    variant?: SidebarVariant;
+    /**
+     * The step below which the rail becomes a drawer over the page.
+     *
+     * A rail is a column when there is a column's worth of room and an overlay
+     * when there is not; below this the rail is `fixed`, covers the page from its
+     * own edge, and closes onto a scrim. `null` pins it as a column at every
+     * width, for a layout that is never narrow — an embedded console, a preview
+     * frame.
+     *
+     * Named, not a number: the switch is a media query in the stylesheet, and a
+     * class built from a runtime number is a class the compiler never emitted. It
+     * also puts the rail on the same four steps as the page around it.
+     */
+    breakpoint?: SidebarBreakpoint | null;
+    /**
+     * A `localStorage` key under which the DOCKED state is remembered.
+     *
+     * A reader who put the rail away did not mean "until the next page". Only the
+     * docked state is kept: an open drawer is a thing a reader did to this screen,
+     * and restoring it on the next visit is a page that opens with its navigation
+     * over the top of itself.
+     *
+     * Read after mount, never during render — a value from storage in the first
+     * pass is a hydration mismatch, and the markup the server sent is the one the
+     * client has to agree with.
+     */
+    persist?: string | null;
+    /**
+     * The drawer covers its nearest positioned ancestor rather than the window.
+     *
+     * For a rail inside a bounded frame — a device preview, an embedded console,
+     * an example on a documentation page. `fixed` resolves against the viewport
+     * wherever the markup sits, so without this the drawer inside a 400px preview
+     * opens across the whole page it is previewed on. Give the frame `relative`.
+     */
+    contained?: boolean;
+    children: ReactNode;
+}
+/**
+ * Holds whether the rail is open, and binds the shortcut that changes it.
+ *
+ * Separate from `Sidebar` itself because the answer is needed on BOTH sides of
+ * the layout: the rail draws itself from it, and the content beside the rail
+ * reserves width from it. A state that lived inside the rail could only ever
+ * be read downwards.
+ */
+declare function SidebarProvider({ open: controlled, defaultOpen, onOpenChange, collapsible, shortcut, side, variant, breakpoint, persist, contained, children, }: SidebarProviderProps): react.JSX.Element;
+interface SidebarProps extends Omit<ComponentProps<'nav'>, 'children'> {
+    /**
+     * Names the landmark. Required: a page with two navigations in it announces
+     * two things called "navigation" unless each of them says which it is.
+     */
+    label: string;
+    /**
+     * What the scrim behind the open drawer announces.
+     *
+     * It is a button — tapping beside a drawer closes it, and that has to be a
+     * control a keyboard and a screen reader can reach, not a decorated `<div>`.
+     */
+    scrimLabel?: string;
+    children: ReactNode;
+}
+/**
+ * A navigation rail down the side of an application.
+ *
+ * A `<nav>`, not an `<aside>`. The element decides the landmark, and a rail of
+ * links announced as "complementary" is not the one a screen reader user jumps
+ * to when they go looking for the navigation.
+ *
+ * Composed rather than configured: a rail is a header, a scrolling middle and a
+ * footer, and every product wants different things in all three. What this owns
+ * is the part that is the same everywhere — the width, the edge, the scroll
+ * behaviour, and what happens when it closes.
+ *
+ * **Closing has three shapes**, and `collapsible` on the provider picks one.
+ * `icon` keeps the rail and drops the labels, which is right when the rows are
+ * a fixed set a reader learns the shape of. `offcanvas` takes the whole rail
+ * away, which is right when the rows are a long index nobody memorises.
+ * `none` is a rail that does not close.
+ *
+ * The trigger belongs INSIDE the rail — `SidebarHeader` places it — rather than
+ * out in an application's masthead. A control that hides a thing should live on
+ * the thing: in the masthead it is one more anonymous icon in a row of them,
+ * and nothing connects it to the column it operates.
+ *
+ * **Under the provider's `breakpoint` it is a drawer**, not a column: `fixed`
+ * against its own edge, over a scrim, and `inert` while closed. Merely
+ * translating it off-screen is not closed — it keeps focus and it is still read
+ * aloud, so a shut drawer puts its whole index between the reader and the page
+ * they were on. The scrim is a real button, because tapping beside a drawer is
+ * how a drawer is closed and that gesture has to exist for a keyboard too.
+ *
+ * `fixed` resolves against the viewport unless an ancestor has a `transform`,
+ * `filter` or `perspective`, which makes that ancestor the containing block
+ * instead. Do not put one on an element wrapping the provider, or the drawer
+ * opens inside it.
+ *
+ * @example
+ * <SidebarProvider>
+ *   <Sidebar label="Documentation">
+ *     <SidebarHeader>Acme</SidebarHeader>
+ *     <SidebarContent>
+ *       <SidebarGroup label="Guide" count={2}>
+ *         <SidebarItem href="/start" icon={Home}>Getting started</SidebarItem>
+ *       </SidebarGroup>
+ *     </SidebarContent>
+ *   </Sidebar>
+ * </SidebarProvider>
+ */
+declare function Sidebar({ label, scrimLabel, className, children, ...rest }: SidebarProps): react.JSX.Element;
+/**
+ * The page beside the rail.
+ *
+ * Every layout built on this component was writing the same
+ * `flex min-w-0 flex-1 flex-col` by hand, and `min-w-0` is the half everybody
+ * forgets: a flex child's floor is its content, so one wide table inside pushes
+ * the whole page past the viewport and takes the rail's width with it.
+ *
+ * It is also the other half of `variant="inset"`. There the rail is the ground
+ * and this is the panel — a bordered `--paper` surface with the ground showing
+ * around it — which is why the variant lives on the provider rather than on
+ * either piece: one setting, two components, and no way to set half of it.
+ *
+ * A `<div>`, not a `<main>`. What goes in here is usually a masthead AND the
+ * page under it, and only one of those is the main landmark.
+ */
+declare function SidebarInset({ className, children, ...rest }: ComponentProps<'div'>): react.JSX.Element;
+/**
+ * The block at the top of the rail: a brand, a workspace, a switcher.
+ *
+ * It is also where `SidebarTrigger` belongs, and the layout assumes one:
+ * anything passed as `children` takes the space and the trigger sits at the
+ * inline end of the row.
+ */
+declare function SidebarHeader({ className, children, ...rest }: ComponentProps<'div'>): react.JSX.Element;
+/** The scrolling middle. Everything that is a list of places goes here. */
+declare function SidebarContent({ className, children, ...rest }: ComponentProps<'div'>): react.JSX.Element;
+/**
+ * The block at the bottom: the utilities, the account, the thing a rail ends on.
+ *
+ * A separate landmark from the content above it because it is a separate kind
+ * of thing — a reader scanning the index does not want Trash and Help in it.
+ */
+declare function SidebarFooter({ className, children, ...rest }: ComponentProps<'div'>): react.JSX.Element;
+/** A rule between blocks of rows, inset to the rail's own padding. */
+declare function SidebarSeparator({ className, ...rest }: ComponentProps<'hr'>): react.JSX.Element;
+interface SidebarTriggerProps extends ComponentProps<'button'> {
+    /** What the button announces. Both states, because it says both things. */
+    labels?: {
+        open: string;
+        close: string;
+    };
+}
+/**
+ * The control that opens and closes the rail.
+ *
+ * Its accessible name changes with what it will DO, and `aria-expanded` reports
+ * what is true now — a button permanently called "Toggle sidebar" tells a
+ * screen reader user nothing about which way it will go.
+ */
+declare function SidebarTrigger({ labels, className, onClick, ...rest }: SidebarTriggerProps): react.JSX.Element;
+interface SidebarGroupProps {
+    /** The heading over the rows. */
+    label: string;
+    /** How many rows are inside, printed on the far side of the heading. */
+    count?: number;
+    /**
+     * A mark that belongs to the GROUP — "Beta", "3 new".
+     *
+     * Beside the label, not out at the end with the count: it qualifies the
+     * words, and a qualifier that has drifted to the other side of the row reads
+     * as a second, unrelated fact.
+     */
+    badge?: ReactNode;
+    /**
+     * A control on the heading row — a menu, an "add" button.
+     *
+     * Sits between the label and the count, and is NOT rendered inside the
+     * heading's own button: a control nested in a control is one the keyboard
+     * reaches by pressing the thing it is inside.
+     */
+    action?: ReactNode;
+    /** Whether the group folds at all. A group of two rows usually should not. */
+    collapsible?: boolean;
+    defaultOpen?: boolean;
+    children: ReactNode;
+    className?: string;
+}
+/**
+ * A labelled block of rows, optionally foldable.
+ *
+ * The heading is the same SIZE as the rows beneath it and outranks them by
+ * weight and by ink. Both halves of that are corrections. Smaller, it inverted
+ * the hierarchy it exists to express — a group read as a footnote over a list
+ * rather than as a title over its own contents. In the MONO face, which is
+ * where it went next, ten of them stacked in a column read as a terminal
+ * listing: mono is this system's voice for code, metadata and figures, and a
+ * navigation heading is none of those. Rank belongs to weight and to a step up
+ * the ink ladder, which are the two signals that can outrank a row without
+ * changing what kind of thing it is.
+ *
+ * An open group draws a hairline down its rows. Fifty rows under seven headings
+ * have nothing in them saying which heading any given row belongs to — only the
+ * distance to the last one, which is gone the moment the list is scrolled.
+ *
+ * The whole block hides when the rail is collapsed to icons: a heading with no
+ * room for its own word is two or three letters and a number, and the rows are
+ * still there underneath as icons.
+ */
+declare function SidebarGroup({ label, count, badge, action, collapsible, defaultOpen, children, className, }: SidebarGroupProps): react.JSX.Element;
+interface SidebarBranchProps {
+    /** The row's own words, and the name of the group it opens. */
+    label: string;
+    /** Drawn at the start of the row, and the whole of the row when collapsed. */
+    icon?: LucideIcon;
+    /** A count or a state at the end of the row. */
+    trailing?: ReactNode;
+    defaultOpen?: boolean;
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    children: ReactNode;
+    className?: string;
+}
+/**
+ * A row that opens onto more rows.
+ *
+ * The thing a rail is for and the thing a flat list of groups cannot do: a
+ * workspace with projects in it, a folder with documents in it, a service with
+ * its environments. `SidebarGroup` is a HEADING over a set — it is not itself a
+ * place, and it has no icon and no state. This is a place that contains places,
+ * so it is a row like any other and it carries the same icon, trailing slot and
+ * hover as its children.
+ *
+ * The children sit behind the same hairline a group draws, one indent further
+ * in, so nesting reads as depth rather than as two unrelated lists. Two levels
+ * is what the indent has room for at this width; a third is a tree, and a tree
+ * in a 16rem column is a horizontal scrollbar with an outline in it.
+ *
+ * Collapsed to icons the row becomes its icon and the children are not drawn —
+ * there is nowhere for an indent to go, and a nested icon under an unnested one
+ * is two glyphs with no visible relationship.
+ *
+ * @example
+ * <SidebarBranch label="Acme HQ" icon={Building} defaultOpen>
+ *   <SidebarItem href="/hq" icon={Home}>Home</SidebarItem>
+ *   <SidebarItem href="/hq/tasks" icon={CheckSquare}>My tasks</SidebarItem>
+ * </SidebarBranch>
+ */
+declare function SidebarBranch({ label, icon: Icon, trailing, defaultOpen, open: controlled, onOpenChange, children, className, }: SidebarBranchProps): react.JSX.Element;
+interface SidebarItemProps extends NavItemProps {
+    /** A count or a state on the far side of the row. Hidden with the label. */
+    trailing?: ReactNode;
+}
+/**
+ * One row.
+ *
+ * `NavItem` with the two things a RAIL adds: a trailing slot, and an answer for
+ * the state where there is no room for words. Collapsed to icons the label is
+ * removed from the layout rather than hidden with CSS — a `sr-only` label still
+ * occupies the flex row's gap — and moves into a tooltip, because an icon on
+ * its own is a guess for everyone and unusable for a screen reader.
+ *
+ * A row with no `icon` keeps its label collapsed, since hiding it would leave a
+ * blank row: the icon is what makes the collapsed state legible, and a rail
+ * that collapses needs one on every row.
+ */
+declare function SidebarItem({ trailing, children, className, onClick, ...rest }: SidebarItemProps): react.JSX.Element;
+
+export { Sidebar, SidebarBranch, type SidebarBranchProps, type SidebarBreakpoint, type SidebarCollapsible, SidebarContent, SidebarFooter, SidebarGroup, type SidebarGroupProps, SidebarHeader, SidebarInset, SidebarItem, type SidebarItemProps, type SidebarProps, SidebarProvider, type SidebarProviderProps, SidebarSeparator, type SidebarSide, SidebarTrigger, type SidebarTriggerProps, type SidebarVariant, useSidebar };