makersclaw 0.2.0 → 0.3.1

package/registry/blocks/sidebar/README.md

@@ -0,0 +1,190 @@
+# Sidebar
+
+An app's navigation down the left edge: the app's name (or a workspace
+switcher), groups of items with icons, counts and nested items, a slot of
+your own, and the signed-in person at the foot with their menu. On a wide
+window it collapses to icons — every label stays, as a tooltip — and
+remembers that. On a phone it is not a column at all: it is a Sheet that
+`SidebarTrigger` opens (from the leading edge; a bottom sheet under
+640px), and it closes when an item is chosen.
+
+```jsx
+import { Sidebar, SidebarLayout, SidebarTrigger } from "../components/blocks/sidebar";   // a Makersclaw app ("./blocks/sidebar" from components/)
+import { Sidebar, SidebarLayout, SidebarTrigger } from "@/components/makersclaw/blocks/sidebar";   // a shadcn project
+```
+
+It is a client component. In a Makersclaw app it belongs in
+`app/shell.jsx`, around the surfaces — the shell's nav is what it replaces.
+
+## The data
+
+`groups` is a list of `{ label?, items }`. An item:
+
+- `label` — what it says (required).
+- `href` — where it goes; rendered as a link (base path applied). Or
+- `onSelect(item)` — what choosing it does. Both may be given.
+- `icon` — a kit icon name. Needed for the icon rail (a missing one shows
+  `file`).
+- `active` — true on the current page: `aria-current="page"` and the
+  highlighted look. The parent of an active item is open to begin with.
+- `badge` — a count or a word, shown on the right; a dot in the rail.
+- `items` — nested items (same shape, one level): the item becomes a
+  collapsible row. In the rail its icon widens the sidebar with it open.
+  With `drilldown` it opens them instead (see Sidebar).
+- `hue` — 1..5: a colour dot in place of the icon (a favourite, a label).
+- `description` — a muted second line (shown on children in drill-in).
+- `actions` — kit `Menu` items: a "…" at the row's end, shown on hover
+  or focus (always on a touch screen). Each `onSelect(item)` may be async
+  and return `{ ok, error? }`; `{ ok: false }` or a throw shows an error
+  toast. Not drawn in the icon rail.
+- `keywords` — extra words the ⌘K search matches, never shown.
+- `disabled` · `key` (default `href`, then `label`).
+
+A group is `{ label?, items, collapsible?, defaultOpen?, key? }`.
+`collapsible: true` makes its heading fold it; `defaultOpen` (default
+true) is where it starts. The icon rail shows every group unfolded.
+
+## Props
+
+### SidebarLayout
+
+- `sidebar` — the `<Sidebar>` element.
+- `children` — the page beside it. Put `<SidebarTrigger />` in its header.
+- `storageKey` — remember collapsed/expanded in this browser under this
+  key. Optional; without it every visit starts at `defaultCollapsed`.
+- `defaultCollapsed` — default `false`.
+- `collapsed` + `onCollapsedChange(next)` — control it yourself instead.
+- `shortcut` — Cmd/Ctrl + this key toggles it; default `"b"`, `null` for none.
+- `variant` — `"inset"` draws the page as a card on the frame's ground.
+  Default: the Sidebar's own `variant`, so you rarely pass it here.
+- `className` — the frame's height and edges (`min-h-dvh` in a shell).
+  Never colour.
+
+### Sidebar
+
+- `groups` — see The data. `items` is the one-group shorthand.
+- `title` — the app's or workspace's name, at the top and on the sheet.
+- `subtitle` — a muted line under it (a plan, a team).
+- `logo` — a node beside the title; default a square `Avatar` of `title`.
+- `switcher` — kit `Menu` items (`[{ label, onSelect, icon? }]`): the title
+  becomes a menu for changing workspace. `switcherLabel` names it
+  (default "Switch workspace"); a reader hears "<title>, <switcherLabel>",
+  so a voice user who says the title still hits it.
+- `user` — `{ name, email?, src? }`, shown at the foot with an `Avatar`.
+- `userMenu` — kit `Menu` items (`[{ label, onSelect, icon?, tone?: "danger",
+  disabled? }]`, and groups and separators): the person becomes a menu
+  button opening these upward (beside the rail when it is icons), flipping
+  where there is no room. A choice also closes the phone sheet.
+- `children` — your own content under the groups (a target, a promo, a
+  help link). Hidden in the icon rail.
+- `label` — the nav landmark's name, default "Main".
+- `className` — layout only. Never colour.
+
+Shapes and extras (all optional; leave them out and it is the column
+above):
+
+- `variant` — `"sidebar"` (default: a bordered column) · `"inset"` (no
+  border; the page beside it becomes a rounded card) · `"floating"` (a
+  rounded card held off the window's edge). A phone is a sheet either way.
+- `headerActions` — a node at the top right: a notifications `Menu`, a
+  button. Hidden in the icon rail; first row of the phone sheet.
+- `switcherPlacement` — `"header"` (default) · `"footer"`: the switcher
+  moves to the foot, over the person, and the top keeps only `logo`.
+- `search` — `true` or `{ placeholder?, hotkey?, label?, empty?,
+  groupLabel? }`: a search row under the top that opens the kit
+  `CommandDialog` over every item (children listed under their parent's
+  name). `hotkey` defaults to `"k"` (⌘K / Ctrl+K), `null` for none. A
+  palette choice runs the item's `onSelect`; an item with only `href`
+  is followed as a page load (the app's base path applied). Give items
+  `onSelect` with `router.push` for a client-side jump.
+- `primaryAction` — `{ label, icon?, onSelect?, href? }`: one button above
+  the groups ("New chat"). `onSelect` may return `{ ok: false, error }`,
+  shown as a toast.
+- `footerActions` — kit `Menu` items behind a "+" beside the person (New
+  deal, Invite). `footerActionsLabel` names it, default "Create". Same
+  `{ ok }` rule as `actions`.
+- `drilldown` — `"inline"` (default: a parent folds open) · `"panel"`
+  (its children open in a second column with a close button; Esc closes
+  it; the icon rail stays narrow beside it) · `"replace"` (its children
+  replace the list, under a Back row). The parent holding the active
+  item starts open. On a phone both are the replace form.
+- `panel` — a second column beside the nav from 768px, 320px wide: your
+  own node, or `{ title?, actions?, search?, items, loading?, error?,
+  onRetry?, empty?, onSelect?, query?, onQueryChange?, filter? }`.
+  - `items`: `[{ key?, title, subtitle?, description?, meta?, icon?,
+    media?, active?, href?, onSelect?, disabled? }]` — a mail is sender
+    (title), date (meta), subject (subtitle), teaser (description).
+  - `search`: `true` or `{ placeholder }`: a field that filters the items
+    here; `filter: false` when you filter them yourself from
+    `onQueryChange(query)`.
+  - `loading` draws skeleton rows, `error` (text) a notice with Try
+    again (`onRetry`), and no items the `empty` line.
+  - On a phone it is the sheet's second screen: choosing a nav item (or
+    the panel's own row at the top) shows it, with a Back row.
+
+### SidebarTrigger
+
+The header button: opens the sheet on a phone, collapses to icons from
+768px. `className` for placement.
+
+### useSidebar()
+
+`{ collapsed, setCollapsed, toggle, mobileOpen, setMobileOpen }` inside a
+`SidebarLayout`, for a control of your own; `null` outside one.
+
+## Example
+
+```jsx
+// app/shell.jsx — the app's shell, the surfaces as the sidebar's items
+"use client";
+import { usePathname } from "next/navigation";
+import { Sidebar, SidebarLayout, SidebarTrigger } from "../components/blocks/sidebar";
+
+const ICONS = { inbox: "inbox", deals: "dollar", contacts: "users", reports: "chart" };
+
+export default function Shell({ name, surfaces, children }) {
+  const pathname = usePathname() ?? "";
+  const activeKey = decodeURIComponent(/^\/s\/([^/?#]+)/.exec(pathname)?.[1] ?? "");
+  const items = surfaces.map((s) => ({
+    key: s.key,
+    label: s.label,
+    href: `/s/${encodeURIComponent(s.key)}`,
+    icon: ICONS[s.key] ?? "file",
+    active: s.key === activeKey,
+    badge: s.built ? undefined : "planned",
+  }));
+  return (
+    <SidebarLayout
+      storageKey={`${name}.sidebar`}
+      className="min-h-dvh"
+      sidebar={<Sidebar title={name} items={items} label={`${name} surfaces`} />}
+    >
+      <header className="flex min-h-14 items-center gap-2 border-b border-border px-2 md:hidden">
+        <SidebarTrigger />
+        <span className="font-semibold">{name}</span>
+      </header>
+      <main className="min-w-0 flex-1 p-4 sm:p-6">{children}</main>
+    </SidebarLayout>
+  );
+}
+```
+
+## What it will not do
+
+- Know the route: say which item is `active` (from `usePathname()`).
+- Nest deeper than one level: a second level is a page of its own.
+- Cover the page on a wide window or dock on the right: floating is a
+  card beside the page, not over it; it is on the left from 768px and a
+  sheet below that.
+- Hold the panel's data: the list, its loading and its errors are yours.
+- Take a colour: it wears the workspace theme.
+
+A sidebar it cannot be is your own component in `components/`, built from
+the kit — not an edit to this block. Its files are fixed: `npm run check`
+refuses a change, and `makersclaw add sidebar` restores them.
+
+## Credits
+
+The inset, floating, search, folding-group, panel, drill-in and item-menu
+shapes follow blocks.so (https://blocks.so, MIT) — a rewrite on the
+Makersclaw kit, none of its code.

package/registry/blocks/sidebar/block.json

@@ -0,0 +1,43 @@
+{
+  "name": "sidebar",
+  "title": "Sidebar",
+  "description": "An app's navigation down the left edge: app name or workspace switcher, groups of items with icons, counts and nested items, the signed-in person with their menu; collapses to icons (remembered) and becomes a Sheet behind a trigger on a phone. Optional: inset or floating look, a ⌘K search over every item, folding groups with colour dots, a second column (a mail list, or a parent's children to drill into), a \"New\" button and a \"…\" menu per item (a chat history).",
+  "useWhen": "An app with more than a handful of places to go (inbox, deals, contacts, reports, settings, projects) that wants a real app shell: compose it in app/shell.jsx around the surfaces. Not for in-page tabs (Tabs) or a short strip of links.",
+  "tags": [
+    "sidebar",
+    "nav",
+    "navigation",
+    "shell",
+    "layout",
+    "menu",
+    "drawer",
+    "collapse",
+    "workspace",
+    "switcher",
+    "app",
+    "rail",
+    "inset",
+    "floating",
+    "search",
+    "command",
+    "palette",
+    "collapsible",
+    "panel",
+    "drilldown",
+    "mail",
+    "chat",
+    "history"
+  ],
+  "exports": [
+    "Sidebar",
+    "SidebarLayout",
+    "SidebarTrigger",
+    "useSidebar"
+  ],
+  "files": [
+    "index.js",
+    "sidebar.jsx",
+    "sidebar-panel.jsx"
+  ],
+  "requires": []
+}