xedonium 0.2.0 → 0.3.0

package/README.md

@@ -6,8 +6,11 @@ Square corners, semantic `app-*` color tokens, light/dark via `<html data-theme>
 ## Install
 
 ```bash
-npm i xedonium      # or: yarn add xedonium
-# peers: react, react-dom, tailwindcss ^3.4
+npm install xedonium
+# or: yarn add xedonium
+# or: pnpm add xedonium
+
+# peers: react, react-dom (18+), tailwindcss ^3.4
 ```
 
 ## Setup
@@ -46,6 +49,7 @@ import { ThemeProvider, AppBar, PageLayout, Button } from 'xedonium'
 ## What's included
 
 - Layout: `AppShell`, `AppBar`, `Navbar`, `Sidebar`, `PageLayout`, `PageHeader`, `Container`, `Flex`, `Stack`, `Grid`, `Card`, `Dashboard`, `Divider`, `Tabs`, `Breadcrumb`
+- Typography: `PageTitle`, `BodyText`, `HelperText`, `Label`, `TextLink`
 - Forms: `Button`, `Field`, `Input`, `Select`, `Checkbox`, `Radio`, `RadioGroup`, `Switch`, `Slider`, `DatePicker`, `DateRangePicker`, `TimePicker`, `FileUpload`
 - Data: `Table`, `DataGrid`, `List`, `SortableList`, `VirtualList`, `Tree`, `Pagination`, `Calendar`, `Carousel`, `Timeline`, `Stepper`, `StatCard`, and charts (`LineChart`, `AreaChart`, `BarChart`, `PieChart`)
 - Feedback and overlays: `Alert`, `Toast`, `Tooltip`, `Modal`, `ConfirmDialog`, `Drawer`, `Popover`, `ActionMenu`, `CommandPalette`, `NotificationCenter`, `Progress`, `Skeleton`, `FanFavicon`, `LoadingScreen`, `RackServer`
@@ -55,20 +59,24 @@ import { ThemeProvider, AppBar, PageLayout, Button } from 'xedonium'
 
 `AppBar` has no router dependency. For react-router pass `linkComponent={Link} linkProp="to"`.
 
-Overlay z-indexes can be overridden with `--xd-z-modal`, `--xd-z-toast`, `--xd-z-tooltip`.
+Overlay z-indexes can be overridden with `--xd-z-modal`, `--xd-z-popover`, `--xd-z-toast`, `--xd-z-tooltip`.
 
 ## Develop
 
 ```bash
-yarn dev     # playground (every component, tabbed) at http://localhost:3100
+yarn docs    # docs site + playground at http://localhost:3100
 yarn build   # dist/ (ESM, CJS, .d.ts, styles.css)
 ```
 
 ## Docs
 
-Docusaurus site in `docs/` (live examples, uses the built `dist/`). Install once with `yarn --cwd docs install`.
+The docs site in `docs/` is a small Vite + React app built with the library itself (imported from `src/`, no build step needed).
+
+- Pages: `docs/src/content/<category>.js` lists each component's page; its demos live in `docs/src/examples/<category>/<slug>-<n>.jsx` and the code shown is exactly the file that is rendered.
+- Props tables: `docs/src/content/props.js`. `yarn docs:check` fails if a component's props and its table drift apart.
 
 ```bash
-yarn docs         # builds the lib, then serves at http://localhost:3000
-yarn docs:build   # static site in docs/build
+yarn docs:build     # static site in docs/dist (+ 404.html for GitHub Pages deep links)
+yarn docs:preview   # serve the production build
+yarn docs:check     # verify props tables and example files
 ```

package/dist/components/ActionMenu.d.ts

@@ -1,13 +1,16 @@
 export default ActionMenu;
 /**
  * Dropdown of page actions. Closes on outside click and Escape (focus returns to the trigger).
+ * The menu is portalled to <body>, so scroll containers and overflow: hidden ancestors can't clip it.
  * items: [{ key, label, description?, badge?, tone?, disabled?, hasDialog?, onClick }]
  * `trigger` is the button content; `variant` styles the trigger (e.g. 'warning' to flag pending work).
+ * `placement` is where the menu opens (default "bottom-start"; e.g. "bottom-end", "top-start"). It flips above or to the other edge when there is no room, and re-adjusts on scroll and resize.
  */
-declare function ActionMenu({ label, trigger, variant, items, className }: {
+declare function ActionMenu({ label, trigger, variant, items, placement, className }: {
     label: any;
     trigger: any;
     variant?: string;
     items: any;
+    placement?: string;
     className?: string;
 }): import("react").JSX.Element;

package/dist/components/AppShell.d.ts

@@ -2,6 +2,7 @@ export default AppShell;
 /**
  * Application frame: header on top, `sidebar` on the left, scrolling `children` as the main area.
  * Below the `md` breakpoint the sidebar moves into a Drawer opened from a menu button in the header.
+ * The drawer closes by itself when the window grows to the `md` breakpoint, where the sidebar is shown inline.
  * `sidebar` may be a node, or a function `(close) => node` if it should close the drawer on selection.
  */
 declare function AppShell({ header, sidebar, sidebarTitle, children, className }: {

package/dist/components/BodyText.d.ts

@@ -0,0 +1,8 @@
+export default BodyText;
+/** Body copy: `text-sm` in the primary text color. `as` changes the element (default p). */
+declare function BodyText({ as: Tag, className, children, ...rest }: {
+    [x: string]: any;
+    as?: string;
+    className?: string;
+    children: any;
+}): import("react").JSX.Element;

package/dist/components/Checkbox.d.ts

@@ -1,5 +1,8 @@
 export default Checkbox;
-/** Checkbox with inline label. `onChange` receives the new boolean. `indeterminate` shows the mixed state. */
+/**
+ * Square checkbox with inline label. `onChange` receives the new boolean. `indeterminate` shows the mixed state.
+ * The native input stays in the DOM (visually hidden) so forms, labels and keyboard behave normally.
+ */
 declare function Checkbox({ label, checked, onChange, indeterminate, disabled, className, ...rest }: {
     [x: string]: any;
     label: any;

package/dist/components/Drawer.d.ts

@@ -1,11 +1,15 @@
 export default Drawer;
-/** Side panel dialog: backdrop, focus trap, Escape / backdrop to close. side: right | left. */
-declare function Drawer({ open, onClose, title, side, width, footer, children }: {
+/**
+ * Side panel dialog: backdrop, focus trap, Escape / backdrop to close. side: right | left.
+ * `padded={false}` removes the body padding and lets the content fill (and scroll) itself, e.g. a Sidebar.
+ */
+declare function Drawer({ open, onClose, title, side, width, padded, footer, children }: {
     open: any;
     onClose: any;
     title: any;
     side?: string;
     width?: string;
+    padded?: boolean;
     footer: any;
     children: any;
 }): any;

package/dist/components/FloatingPanel.d.ts

@@ -0,0 +1,21 @@
+export default FloatingPanel;
+/**
+ * A panel positioned next to `anchorRef`'s element, rendered into <body> with fixed positioning so no
+ * ancestor (overflow: hidden, transforms, dialogs) can clip it. It flips to the opposite side when there is
+ * no room, stays inside the viewport and follows the anchor on scroll and resize.
+ *
+ * placement: top | bottom | left | right | auto, optionally with -start / -end (e.g. "bottom-end").
+ * `matchWidth` makes the panel at least as wide as the anchor. Pass `panelRef` to read the element.
+ */
+declare function FloatingPanel({ open, anchorRef, placement, gap, matchWidth, panelRef, className, style, children, ...rest }: {
+    [x: string]: any;
+    open: any;
+    anchorRef: any;
+    placement?: string;
+    gap?: number;
+    matchWidth?: boolean;
+    panelRef: any;
+    className?: string;
+    style: any;
+    children: any;
+}): any;

package/dist/components/HelperText.d.ts

@@ -0,0 +1,8 @@
+export default HelperText;
+/** Secondary text for hints and captions: `text-xs` in the muted color. `as` changes the element (default p). */
+declare function HelperText({ as: Tag, className, children, ...rest }: {
+    [x: string]: any;
+    as?: string;
+    className?: string;
+    children: any;
+}): import("react").JSX.Element;

package/dist/components/Label.d.ts

@@ -0,0 +1,12 @@
+export default Label;
+/**
+ * Small uppercase label. Renders a real <label> when `htmlFor` is given (use it for form controls), otherwise a
+ * <span>; `as` overrides the element.
+ */
+declare function Label({ as, htmlFor, className, children, ...rest }: {
+    [x: string]: any;
+    as: any;
+    htmlFor: any;
+    className?: string;
+    children: any;
+}): import("react").JSX.Element;

package/dist/components/PageTitle.d.ts

@@ -0,0 +1,8 @@
+export default PageTitle;
+/** Page heading: bold, tight tracking, 2xl on phones and 3xl from `sm`. `as` changes the element (default h1). */
+declare function PageTitle({ as: Tag, className, children, ...rest }: {
+    [x: string]: any;
+    as?: string;
+    className?: string;
+    children: any;
+}): import("react").JSX.Element;

package/dist/components/Popover.d.ts

@@ -1,13 +1,17 @@
 export default Popover;
 /**
  * Button that toggles a floating panel with arbitrary content. Closes on outside click and Escape
- * (focus returns to the trigger). align: start | end. Use ActionMenu for a plain list of actions.
+ * (focus returns to the trigger). The panel is portalled to <body>, so it is never clipped by an
+ * ancestor, and it flips when there is no room.
+ * placement: top | bottom | left | right | auto, optionally with -start / -end. `align` (start | end) is the
+ * shorthand for bottom-start / bottom-end. Use ActionMenu for a plain list of actions.
  */
-declare function Popover({ trigger, label, variant, align, className, children }: {
+declare function Popover({ trigger, label, variant, align, placement, className, children }: {
     trigger: any;
     label: any;
     variant?: string;
     align?: string;
+    placement: any;
     className?: string;
     children: any;
 }): import("react").JSX.Element;

package/dist/components/Select.d.ts

@@ -1,6 +1,10 @@
 export default Select;
-/** Labelled native select. options: [{ value, label, disabled? }]. `onChange` receives the value string. */
-declare function Select({ label, value, onChange, options, placeholder, error, className, ...rest }: {
+/**
+ * Labelled select with a themed listbox (portalled, so it is never clipped). Keyboard: Up / Down / Home / End move,
+ * Enter or Space picks, Escape closes, typing jumps to a matching option.
+ * options: [{ value, label, disabled? }]. `onChange` receives the value string. `name` adds a hidden input for forms.
+ */
+declare function Select({ label, value, onChange, options, placeholder, error, disabled, name, className, ...rest }: {
     [x: string]: any;
     label: any;
     value: any;
@@ -8,5 +12,7 @@ declare function Select({ label, value, onChange, options, placeholder, error, c
     options: any;
     placeholder: any;
     error: any;
+    disabled?: boolean;
+    name: any;
     className?: string;
 }): import("react").JSX.Element;

package/dist/components/Slider.d.ts

@@ -1,5 +1,5 @@
 export default Slider;
-/** Range input. `onChange` receives a number. */
+/** Range input with a square thumb and a filled track (styled in styles.css). `onChange` receives a number. */
 declare function Slider({ label, value, onChange, min, max, step, showValue, className, ...rest }: {
     [x: string]: any;
     label: any;

package/dist/components/TextLink.d.ts

@@ -0,0 +1,13 @@
+export default TextLink;
+/**
+ * Underlined inline link with a hover color. `linkComponent` / `linkProp` swap in a router link, as in AppBar
+ * (e.g. `linkComponent={Link} linkProp="to"`).
+ */
+declare function TextLink({ href, linkComponent: Link, linkProp, className, children, ...rest }: {
+    [x: string]: any;
+    href: any;
+    linkComponent?: string;
+    linkProp?: string;
+    className?: string;
+    children: any;
+}): import("react").JSX.Element;

package/dist/components/TimePicker.d.ts

@@ -1,6 +1,10 @@
 export default TimePicker;
-/** Labelled time field using the native time control. `value` / `onChange` use "HH:MM" strings. `step` is in seconds. */
-declare function TimePicker({ label, value, onChange, step, min, max, error, ...rest }: {
+/**
+ * Time field with a themed hour / minute picker (no native control). `value` / `onChange` use 24-hour "HH:MM" strings.
+ * `step` is the minute granularity in seconds (default 900 = 15 min). `min` / `max` ("HH:MM") disable times outside
+ * them. `hour12` shows the hours on a 12-hour clock with AM / PM (the value stays 24-hour).
+ */
+declare function TimePicker({ label, value, onChange, step, min, max, hour12, placeholder, error, disabled, className, ...rest }: {
     [x: string]: any;
     label: any;
     value: any;
@@ -8,5 +12,9 @@ declare function TimePicker({ label, value, onChange, step, min, max, error, ...
     step?: number;
     min: any;
     max: any;
+    hour12?: boolean;
+    placeholder?: string;
     error: any;
+    disabled?: boolean;
+    className?: string;
 }): import("react").JSX.Element;

package/dist/components/Tooltip.d.ts

@@ -1,6 +1,7 @@
 export default Tooltip;
-declare function Tooltip({ text, children, className }: {
+declare function Tooltip({ text, children, placement, className }: {
     text: any;
     children: any;
+    placement?: string;
     className?: string;
 }): any;

package/dist/hooks/useDismissable.d.ts

@@ -1,2 +1,2 @@
 export default useDismissable;
-declare function useDismissable(open: any, rootRef: any, onDismiss: any): void;
+declare function useDismissable(open: any, insideRefs: any, onDismiss: any): void;

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export { default as AppShell } from "./components/AppShell";
 export { default as AreaChart } from "./components/AreaChart";
 export { default as Avatar } from "./components/Avatar";
 export { default as BarChart } from "./components/BarChart";
+export { default as BodyText } from "./components/BodyText";
 export { default as Breadcrumb } from "./components/Breadcrumb";
 export { default as Button } from "./components/Button";
 export { default as Calendar } from "./components/Calendar";
@@ -26,8 +27,10 @@ export { default as FileUpload } from "./components/FileUpload";
 export { default as Flex } from "./components/Flex";
 export { default as FocusTrap } from "./components/FocusTrap";
 export { default as Grid } from "./components/Grid";
+export { default as HelperText } from "./components/HelperText";
 export { default as Image } from "./components/Image";
 export { default as Input } from "./components/Input";
+export { default as Label } from "./components/Label";
 export { default as LineChart } from "./components/LineChart";
 export { default as List } from "./components/List";
 export { default as LoadingScreen } from "./components/LoadingScreen";
@@ -36,6 +39,7 @@ export { default as Navbar } from "./components/Navbar";
 export { default as NotificationCenter } from "./components/NotificationCenter";
 export { default as PageHeader } from "./components/PageHeader";
 export { default as PageLayout } from "./components/PageLayout";
+export { default as PageTitle } from "./components/PageTitle";
 export { default as Pagination } from "./components/Pagination";
 export { default as PieChart } from "./components/PieChart";
 export { default as Popover } from "./components/Popover";
@@ -55,6 +59,7 @@ export { default as Stepper } from "./components/Stepper";
 export { default as Switch } from "./components/Switch";
 export { default as Table } from "./components/Table";
 export { default as Tabs } from "./components/Tabs";
+export { default as TextLink } from "./components/TextLink";
 export { default as ThemeToggle } from "./components/ThemeToggle";
 export { default as Timeline } from "./components/Timeline";
 export { default as TimePicker } from "./components/TimePicker";

package/dist/styles.css

@@ -77,3 +77,91 @@ body {
 		scroll-behavior: auto !important;
 	}
 }
+
+/* Square scrollbars in both themes (WebKit/Blink); Firefox gets thin themed bars via scrollbar-color */
+::-webkit-scrollbar {
+	width: 12px;
+	height: 12px;
+}
+
+::-webkit-scrollbar-track,
+::-webkit-scrollbar-corner {
+	background: rgb(var(--color-app-bg));
+	border-radius: 0;
+}
+
+::-webkit-scrollbar-thumb {
+	background: rgb(var(--color-app-border));
+	border: 3px solid rgb(var(--color-app-bg));
+	border-radius: 0;
+}
+
+::-webkit-scrollbar-thumb:hover {
+	background: rgb(var(--color-app-muted));
+}
+
+@supports not selector(::-webkit-scrollbar) {
+	* {
+		scrollbar-width: thin;
+		scrollbar-color: rgb(var(--color-app-border)) rgb(var(--color-app-bg));
+	}
+}
+
+/* Slider: square thumb, filled track. --xd-fill (set by <Slider>) is the filled percentage. */
+.xd-slider {
+	-webkit-appearance: none;
+	appearance: none;
+	height: 18px;
+	margin: 0;
+	background: transparent;
+	cursor: pointer;
+}
+
+.xd-slider:disabled {
+	cursor: not-allowed;
+	opacity: 0.5;
+}
+
+.xd-slider::-webkit-slider-runnable-track {
+	height: 4px;
+	border-radius: 0;
+	background: linear-gradient(
+		to right,
+		rgb(var(--color-app-strong)) var(--xd-fill, 0%),
+		rgb(var(--color-app-border)) var(--xd-fill, 0%)
+	);
+}
+
+.xd-slider::-webkit-slider-thumb {
+	-webkit-appearance: none;
+	appearance: none;
+	width: 14px;
+	height: 14px;
+	margin-top: -5px;
+	border: 2px solid rgb(var(--color-app-bg));
+	border-radius: 0;
+	background: rgb(var(--color-app-strong));
+	box-shadow: 0 0 0 1px rgb(var(--color-app-strong));
+}
+
+.xd-slider::-moz-range-track {
+	height: 4px;
+	border-radius: 0;
+	background: rgb(var(--color-app-border));
+}
+
+.xd-slider::-moz-range-progress {
+	height: 4px;
+	border-radius: 0;
+	background: rgb(var(--color-app-strong));
+}
+
+.xd-slider::-moz-range-thumb {
+	box-sizing: border-box;
+	width: 14px;
+	height: 14px;
+	border: 2px solid rgb(var(--color-app-bg));
+	border-radius: 0;
+	background: rgb(var(--color-app-strong));
+	box-shadow: 0 0 0 1px rgb(var(--color-app-strong));
+}

package/dist/utils/position.d.ts

@@ -0,0 +1,14 @@
+export function parsePlacement(placement?: string): {
+    side: string;
+    align: string;
+};
+export function computePosition(anchor: any, panel: any, { placement, gap, viewport }?: {
+    placement?: string;
+    gap?: number;
+}): {
+    top: number;
+    left: number;
+    side: string;
+    align: string;
+};
+export function isClipped(element: any): boolean;