@olwiba/ui 0.2.24 → 0.2.26

package/site/demos/underlay.tsx

@@ -0,0 +1,74 @@
+'use client';
+
+import * as React from 'react';
+import { Underlay, type UnderlayVariant } from '@olwiba/ui';
+import { DemoControls, useUsageCode } from '~/components/ComponentPreview';
+import { Button, Badge } from '@olwiba/cn';
+
+const variants: UnderlayVariant[] = ['dots', 'lines', 'cross', 'glow'];
+
+function MockContent() {
+  return (
+    <div className="relative z-10 flex w-full flex-col gap-4 p-8">
+      <div className="flex items-center justify-between">
+        <div>
+          <p className="text-xs text-muted-foreground">Total revenue</p>
+          <p className="text-2xl font-semibold">$48,295</p>
+        </div>
+        <Badge variant="secondary">+12.4%</Badge>
+      </div>
+      <div className="flex gap-3">
+        {['Mon', 'Tue', 'Wed', 'Thu', 'Fri'].map((d, i) => (
+          <div key={d} className="flex flex-1 flex-col items-center gap-1">
+            <div
+              className="w-full rounded bg-primary/20"
+              style={{ height: `${[40, 65, 50, 80, 55][i]}px` }}
+            />
+            <span className="text-[10px] text-muted-foreground">{d}</span>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+export default function UnderlayDemo() {
+  const [variant, setVariant] = React.useState<UnderlayVariant>('dots');
+
+  const extraProps = variant === 'glow' ? ` size={320} followCursor blur="xl"` : '';
+
+  useUsageCode(
+    `<div className="relative overflow-hidden rounded-xl">\n  <Underlay variant="${variant}"${extraProps} />\n  <div className="relative z-10 p-8">Content</div>\n</div>`,
+  );
+
+  return (
+    <>
+      <div className="relative w-full overflow-hidden bg-card">
+        <Underlay
+          key={variant}
+          variant={variant}
+          {...(variant === 'glow' ? { size: 360, followCursor: true, blur: 'xl' as const } : {})}
+        />
+        <MockContent />
+      </div>
+
+      <DemoControls>
+        <div className="space-y-1.5">
+          <span className="text-xs font-medium text-muted-foreground">Variant</span>
+          <div className="flex flex-wrap gap-1.5">
+            {variants.map((v) => (
+              <Button
+                key={v}
+                variant={variant === v ? 'default' : 'secondary'}
+                size="sm"
+                onClick={() => setVariant(v)}
+              >
+                {v}
+              </Button>
+            ))}
+          </div>
+        </div>
+      </DemoControls>
+    </>
+  );
+}

package/site/demos/update-banner.tsx

@@ -0,0 +1,31 @@
+import { UpdateBanner } from '@olwiba/ui';
+import * as React from 'react';
+
+export default function UpdateBannerDemo() {
+  const [show, setShow] = React.useState(true);
+
+  return (
+    <div className="relative min-h-[260px] overflow-hidden rounded-2xl border bg-background p-6">
+      <p className="text-sm text-muted-foreground">
+        The banner polls a version endpoint and slides in when the deployed version no longer matches
+        the running bundle. This demo forces it visible.
+      </p>
+      <button
+        className="mt-4 rounded-md border px-3 py-1.5 text-sm"
+        onClick={() => setShow((value) => !value)}
+      >
+        Toggle banner
+      </button>
+
+      {/* Demo container overrides the fixed positioning context */}
+      <div className="absolute inset-0 [&>div]:absolute [&>div]:top-4">
+        <UpdateBanner
+          forceShow={show}
+          currentVersion="dev-local"
+          fetchVersion={async () => ({ version: 'dev-local' })}
+          onRefresh={() => setShow(false)}
+        />
+      </div>
+    </div>
+  );
+}

package/site/demos/use-copy-to-clipboard.tsx

@@ -0,0 +1,21 @@
+'use client';
+import { useCopyToClipboard } from '@olwiba/ui';
+import { Button } from '@olwiba/cn';
+import { Check, Copy } from 'lucide-react';
+
+const snippet = 'bun add @olwiba/ui @olwiba/cn';
+
+export default function Demo() {
+  const [copied, copy] = useCopyToClipboard();
+
+  return (
+    <div className="flex items-center justify-center p-8">
+      <div className="flex items-center gap-2 rounded-xl border bg-muted px-4 py-2">
+        <code className="font-mono text-sm">{snippet}</code>
+        <Button size="icon" variant="ghost" className="size-7 shrink-0" onClick={() => copy(snippet)}>
+          {copied ? <Check className="size-3.5 text-emerald-500" /> : <Copy className="size-3.5" />}
+        </Button>
+      </div>
+    </div>
+  );
+}

package/site/demos/use-debounce.tsx

@@ -0,0 +1,25 @@
+'use client';
+import * as React from 'react';
+import { useDebounce } from '@olwiba/ui';
+import { Input } from '@olwiba/cn';
+
+export default function Demo() {
+  const [value, setValue] = React.useState('');
+  const debounced = useDebounce(value, 400);
+
+  return (
+    <div className="mx-auto flex max-w-sm flex-col gap-4 p-8">
+      <Input placeholder="Type something..." value={value} onChange={(e) => setValue(e.target.value)} />
+      <div className="space-y-1 rounded-xl border bg-card p-4 text-sm">
+        <div className="flex justify-between gap-4">
+          <span className="text-muted-foreground">Live</span>
+          <span className="font-mono">{value || '—'}</span>
+        </div>
+        <div className="flex justify-between gap-4">
+          <span className="text-muted-foreground">Debounced (400ms)</span>
+          <span className="font-mono">{debounced || '—'}</span>
+        </div>
+      </div>
+    </div>
+  );
+}

package/site/demos/use-intersection-observer.tsx

@@ -0,0 +1,32 @@
+'use client';
+import * as React from 'react';
+import { useIntersectionObserver } from '@olwiba/ui';
+import { cn } from '@olwiba/cn';
+
+export default function Demo() {
+  const [ref, isVisible] = useIntersectionObserver({ threshold: 0.5 });
+
+  return (
+    <div className="space-y-3 p-6">
+      <div className="text-sm text-center">
+        Status:{' '}
+        <strong className={isVisible ? 'text-emerald-500' : 'text-muted-foreground'}>
+          {isVisible ? 'intersecting' : 'not intersecting'}
+        </strong>
+      </div>
+      <div className="h-44 overflow-y-auto rounded-xl border">
+        <div className="flex h-16 items-center justify-center text-xs text-muted-foreground">↓ scroll</div>
+        <div
+          ref={ref as unknown as React.RefObject<HTMLDivElement>}
+          className={cn(
+            'mx-4 rounded-xl border p-4 text-sm text-center transition-all duration-500',
+            isVisible ? 'border-primary bg-primary/5 text-primary' : 'bg-muted text-muted-foreground',
+          )}
+        >
+          Observed element
+        </div>
+        <div className="flex h-16 items-center justify-center text-xs text-muted-foreground">↑ scroll</div>
+      </div>
+    </div>
+  );
+}

package/site/demos/use-local-storage.tsx

@@ -0,0 +1,22 @@
+'use client';
+import { useLocalStorage } from '@olwiba/ui';
+import { Button } from '@olwiba/cn';
+
+export default function Demo() {
+  const [count, setCount] = useLocalStorage('demo-count', 0);
+
+  return (
+    <div className="flex flex-col items-center gap-4 p-8">
+      <div className="w-40 rounded-2xl border bg-card p-6 text-center">
+        <div className="text-4xl font-bold tabular-nums">{count}</div>
+        <div className="mt-1 text-xs text-muted-foreground">persisted in localStorage</div>
+      </div>
+      <div className="flex gap-2">
+        <Button variant="outline" size="sm" onClick={() => setCount(count - 1)}>−</Button>
+        <Button variant="outline" size="sm" onClick={() => setCount(0)}>Reset</Button>
+        <Button size="sm" onClick={() => setCount(count + 1)}>+</Button>
+      </div>
+      <p className="text-xs text-muted-foreground">Value persists across page reloads.</p>
+    </div>
+  );
+}

package/site/demos/use-media-query.tsx

@@ -0,0 +1,31 @@
+'use client';
+import { useMediaQuery } from '@olwiba/ui';
+import { cn } from '@olwiba/cn';
+
+const breakpoints = [
+  { label: 'sm', query: '(min-width: 640px)' },
+  { label: 'md', query: '(min-width: 768px)' },
+  { label: 'lg', query: '(min-width: 1024px)' },
+  { label: 'xl', query: '(min-width: 1280px)' },
+  { label: 'dark', query: '(prefers-color-scheme: dark)' },
+];
+
+function Row({ label, query }: { label: string; query: string }) {
+  const matches = useMediaQuery(query);
+  return (
+    <div className={cn('flex items-center justify-between rounded-xl border px-4 py-2.5 text-sm transition-colors', matches ? 'border-primary bg-primary/5' : 'bg-card')}>
+      <code className="font-mono text-xs">{query}</code>
+      <span className={cn('text-xs font-medium', matches ? 'text-primary' : 'text-muted-foreground')}>
+        {matches ? 'matches' : 'no match'}
+      </span>
+    </div>
+  );
+}
+
+export default function Demo() {
+  return (
+    <div className="flex flex-col gap-2 p-6">
+      {breakpoints.map((bp) => <Row key={bp.label} {...bp} />)}
+    </div>
+  );
+}

package/site/demos/use-pagination.tsx

@@ -0,0 +1,31 @@
+'use client';
+import { usePagination } from '@olwiba/ui';
+import { Button } from '@olwiba/cn';
+
+const ALL_ITEMS = Array.from({ length: 23 }, (_, i) => `Item ${i + 1}`);
+
+export default function Demo() {
+  const { page, totalPages, offset, pageSize, hasPrev, hasNext, prev, next, goTo } = usePagination(ALL_ITEMS.length, 5);
+  const pageItems = ALL_ITEMS.slice(offset, offset + pageSize);
+
+  return (
+    <div className="flex flex-col gap-4 p-6">
+      <div className="space-y-1.5">
+        {pageItems.map((item) => (
+          <div key={item} className="rounded-xl border bg-card px-4 py-2.5 text-sm">{item}</div>
+        ))}
+      </div>
+      <div className="flex items-center justify-between gap-2">
+        <Button variant="outline" size="sm" disabled={!hasPrev} onClick={prev}>Previous</Button>
+        <div className="flex gap-1">
+          {Array.from({ length: totalPages }, (_, i) => (
+            <Button key={i} size="sm" variant={page === i + 1 ? 'default' : 'outline'} className="size-8 p-0" onClick={() => goTo(i + 1)}>
+              {i + 1}
+            </Button>
+          ))}
+        </div>
+        <Button variant="outline" size="sm" disabled={!hasNext} onClick={next}>Next</Button>
+      </div>
+    </div>
+  );
+}

package/site/demos/user-profile-block.tsx

@@ -0,0 +1,3 @@
+export default function Demo() {
+  return <div className="p-8 text-muted-foreground text-sm">UserProfileBlock — coming soon</div>;
+}

package/site/demos/version-banner.tsx

@@ -0,0 +1,27 @@
+import { VersionBanner } from '@olwiba/ui';
+import * as React from 'react';
+
+export default function VersionBannerDemo() {
+  const [show, setShow] = React.useState(true);
+
+  return (
+    <div className="w-full max-w-lg rounded-lg border overflow-hidden">
+      {show ? (
+        <VersionBanner
+          version="2.1.0"
+          message="New components available — see what's changed."
+          onDismiss={() => setShow(false)}
+        />
+      ) : (
+        <div className="flex items-center justify-center py-4">
+          <button
+            onClick={() => setShow(true)}
+            className="text-sm text-muted-foreground underline"
+          >
+            Reset demo
+          </button>
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/Chart.tsx

@@ -42,6 +42,27 @@ export interface ChartProps {
   grid?: boolean;
   /** Legend. @default true for multiple series or donut, false for one series */
   legend?: boolean;
+  /**
+   * Stack series instead of overlaying them. Area and bar only — a stacked
+   * line is a shape people misread as absolute values.
+   *
+   * Off by default: stacking answers "what does the total split into", and
+   * silently switching a two-series comparison to it would change what an
+   * existing chart claims.
+   */
+  stacked?: boolean;
+  /**
+   * Formats x-axis ticks. Separate from `valueFormatter`, which formats the
+   * measured value — an axis of ISO dates wants shortening without changing
+   * what the tooltip reports.
+   */
+  xTickFormatter?: (value: string) => string;
+  /**
+   * Fixes the y-axis range. Without it recharts scales to the data, which for
+   * a percentage series makes a 98-100%% band fill the plot and read as
+   * volatility.
+   */
+  yDomain?: [number, number];
   /** Formats values in tooltips and the y-axis, e.g. `(v) => \`$${v}\``. */
   valueFormatter?: (value: number) => string;
   className?: string;
@@ -121,6 +142,9 @@ export function Chart({
   height = 300,
   grid = true,
   legend,
+  stacked = false,
+  xTickFormatter,
+  yDomain,
   valueFormatter = (v) => String(v),
   className,
 }: ChartProps) {
@@ -170,11 +194,12 @@ export function Chart({
       chart = (
         <BarChart data={data} barCategoryGap="25%">
           {gridEl}
-          <XAxis dataKey={xKey} {...axisProps} />
-          <YAxis {...axisProps} width={48} tickFormatter={valueFormatter} />
+          <XAxis dataKey={xKey} {...axisProps} tickFormatter={xTickFormatter} />
+          <YAxis {...axisProps} width={48} domain={yDomain} tickFormatter={valueFormatter} />
           {tooltip}
           {series.map((s, i) => (
             <Bar
+              stackId={stacked ? 'stack' : undefined}
               key={s.key}
               dataKey={s.key}
               name={s.label ?? s.key}
@@ -189,8 +214,8 @@ export function Chart({
       chart = (
         <AreaChart data={data}>
           {gridEl}
-          <XAxis dataKey={xKey} {...axisProps} />
-          <YAxis {...axisProps} width={48} tickFormatter={valueFormatter} />
+          <XAxis dataKey={xKey} {...axisProps} tickFormatter={xTickFormatter} />
+          <YAxis {...axisProps} width={48} domain={yDomain} tickFormatter={valueFormatter} />
           {tooltip}
           {series.map((s, i) => (
             <Area
@@ -198,10 +223,16 @@ export function Chart({
               type="monotone"
               dataKey={s.key}
               name={s.label ?? s.key}
+              // One shared id is what makes recharts stack rather than
+              // overlay; undefined leaves the existing behaviour untouched.
+              stackId={stacked ? 'stack' : undefined}
               stroke={seriesColor(s, i)}
               strokeWidth={2}
               fill={seriesColor(s, i)}
-              fillOpacity={0.12}
+              // Overlaid areas must stay translucent so the ones behind show
+              // through. Stacked bands never overlap, and at 0.12 they are too
+              // faint to tell apart.
+              fillOpacity={stacked ? 0.35 : 0.12}
               dot={false}
               activeDot={{ r: 4 }}
             />
@@ -212,8 +243,8 @@ export function Chart({
       chart = (
         <LineChart data={data}>
           {gridEl}
-          <XAxis dataKey={xKey} {...axisProps} />
-          <YAxis {...axisProps} width={48} tickFormatter={valueFormatter} />
+          <XAxis dataKey={xKey} {...axisProps} tickFormatter={xTickFormatter} />
+          <YAxis {...axisProps} width={48} domain={yDomain} tickFormatter={valueFormatter} />
           {tooltip}
           {series.map((s, i) => (
             <Line

package/src/components/DataTable.tsx

@@ -26,6 +26,23 @@ export interface DataTableProps<TData> {
   onSelectionChange?: (rows: TData[]) => void;
   /** Rows per page. Set to `0` to disable pagination entirely. @default 10 */
   pageSize?: number;
+  /**
+   * Hands pagination to the caller, for data the client does not hold all of.
+   *
+   * With this set, `data` is treated as the current page rather than the whole
+   * set: the table stops slicing, and the footer reports and drives the
+   * caller's page instead of its own. Without it nothing changes — a table
+   * given every row keeps paginating locally, which is right for the common
+   * case and avoids making every consumer implement paging to get a table.
+   */
+  pagination?: {
+    pageIndex: number;
+    /** Total pages. Omit when unknown — the footer then relies on `hasNext`. */
+    pageCount?: number;
+    hasNext?: boolean;
+    hasPrevious?: boolean;
+    onPageChange: (pageIndex: number) => void;
+  };
   /** Slot rendered top-right of the toolbar — e.g. an "Add" button. */
   toolbar?: React.ReactNode;
   onRowClick?: (row: TData) => void;
@@ -66,6 +83,7 @@ export function DataTable<TData>({
   selectable = false,
   onSelectionChange,
   pageSize = 10,
+  pagination,
   toolbar,
   onRowClick,
   emptyMessage = 'No results.',
@@ -94,8 +112,13 @@ export function DataTable<TData>({
     },
     getCoreRowModel: getCoreRowModel(),
     getSortedRowModel: getSortedRowModel(),
-    ...(pageSize > 0 ? { getPaginationRowModel: getPaginationRowModel() } : {}),
-    initialState: pageSize > 0 ? { pagination: { pageSize } } : undefined,
+    // Server-paginated tables must not slice: `data` is already the page, and
+    // running the client model over it would paginate a single page again.
+    ...(pageSize > 0 && !pagination
+      ? { getPaginationRowModel: getPaginationRowModel() }
+      : {}),
+    ...(pagination ? { manualPagination: true } : {}),
+    initialState: pageSize > 0 && !pagination ? { pagination: { pageSize } } : undefined,
     enableRowSelection: selectable,
   });
 
@@ -107,6 +130,31 @@ export function DataTable<TData>({
 
   const rows = table.getRowModel().rows;
 
+  // One set of derivations so the footer does not branch on `pagination`
+  // three separate times and drift between them.
+  const canPrevious = pagination
+    ? (pagination.hasPrevious ?? pagination.pageIndex > 0)
+    : table.getCanPreviousPage();
+  const canNext = pagination
+    ? (pagination.hasNext ??
+      (pagination.pageCount !== undefined && pagination.pageIndex < pagination.pageCount - 1))
+    : table.getCanNextPage();
+  const goPrevious = () =>
+    pagination ? pagination.onPageChange(pagination.pageIndex - 1) : table.previousPage();
+  const goNext = () =>
+    pagination ? pagination.onPageChange(pagination.pageIndex + 1) : table.nextPage();
+  // A server-paginated table shows its pager whenever paging is possible.
+  // Total pages are often unknown, so "more than one page" is not a question
+  // it can answer up front the way the local model can.
+  const showPager = pagination
+    ? canPrevious || canNext
+    : pageSize > 0 && table.getPageCount() > 1;
+  const pageLabel = pagination
+    ? pagination.pageCount !== undefined
+      ? `Page ${pagination.pageIndex + 1} of ${pagination.pageCount}`
+      : `Page ${pagination.pageIndex + 1}`
+    : `Page ${table.getState().pagination.pageIndex + 1} of ${table.getPageCount()}`;
+
   return (
     <div className={cn('space-y-4', className)}>
       {(searchKey || toolbar) && (
@@ -186,19 +234,19 @@ export function DataTable<TData>({
         </Table>
       </div>
 
-      {(selectable || (pageSize > 0 && table.getPageCount() > 1)) && (
+      {(selectable || showPager) && (
         <div className="flex items-center justify-between">
           <p className="text-sm text-muted-foreground">
             {selectable && `${table.getFilteredSelectedRowModel().rows.length} of ${table.getFilteredRowModel().rows.length} selected`}
-            {selectable && pageSize > 0 && table.getPageCount() > 1 && ' · '}
-            {pageSize > 0 && table.getPageCount() > 1 && `Page ${table.getState().pagination.pageIndex + 1} of ${table.getPageCount()}`}
+            {selectable && showPager && ' · '}
+            {showPager && pageLabel}
           </p>
-          {pageSize > 0 && table.getPageCount() > 1 && (
+          {showPager && (
             <div className="flex gap-2">
-              <Button variant="outline" size="sm" onClick={() => table.previousPage()} disabled={!table.getCanPreviousPage()}>
+              <Button variant="outline" size="sm" onClick={goPrevious} disabled={!canPrevious}>
                 <ChevronLeft className="size-4" /> Previous
               </Button>
-              <Button variant="outline" size="sm" onClick={() => table.nextPage()} disabled={!table.getCanNextPage()}>
+              <Button variant="outline" size="sm" onClick={goNext} disabled={!canNext}>
                 Next <ChevronRight className="size-4" />
               </Button>
             </div>

package/src/components/Notify.tsx

@@ -86,11 +86,42 @@ export function NotificationToast({
 }
 
 export interface NotifyOptions extends Omit<NotificationToastProps, 'onDismiss'> {
+  /**
+   * Overrides the per-variant default below. Explicit always wins — a caller
+   * that has thought about the timing knows more than this heuristic does.
+   */
   duration?: number;
 }
 
+/**
+ * How long a toast stays, when the caller has not said.
+ *
+ * The Toaster's own default suits a confirmation: long enough to read "Saved",
+ * short enough not to linger. Two cases need longer, and both were previously
+ * left to whoever remembered to pass a number.
+ *
+ * A failure has to be *read* — often it is the only account of what went
+ * wrong, and a message that vanishes before it is understood is barely better
+ * than none. A toast carrying an action has to be read *and* decided on, and a
+ * button that disappears mid-reach is worse than no button, because the reader
+ * knows they missed something.
+ *
+ * Returning undefined defers to the Toaster, so a product that has set its own
+ * default keeps it rather than being silently overridden here.
+ */
+function defaultDuration(variant: NotificationToastProps['variant'], hasAction: boolean) {
+  if (variant === 'error') return 10_000;
+  if (variant === 'warning') return 8_000;
+  if (hasAction) return 8_000;
+  return undefined;
+}
+
 /** Fires a `NotificationToast` through sonner. Requires `<Toaster />` from `@olwiba/cn` mounted once in your app. */
 export function notify(options: NotifyOptions) {
   const { duration, ...toastProps } = options;
-  return toast.custom((id) => <NotificationToast {...toastProps} onDismiss={() => toast.dismiss(id)} />, { duration });
+  const resolved =
+    duration ?? defaultDuration(toastProps.variant, Boolean(toastProps.action || toastProps.secondaryAction));
+  return toast.custom((id) => <NotificationToast {...toastProps} onDismiss={() => toast.dismiss(id)} />, {
+    duration: resolved,
+  });
 }

package/src/email/EmailLinkFallback.tsx

@@ -17,7 +17,13 @@ export function EmailLinkFallback({
         {label}
       </EmailText>
       <EmailText style={{ margin: 0 }}>
-        <EmailLink href={actionUrl} brandColor={brandColor}>
+        {/*
+          Set through `style` rather than CN's `brandColor` prop, which this
+          package's pinned @olwiba/cn does not have yet. CN applies that prop as
+          `color` anyway, and `style` wins over its default, so the result is
+          identical without coupling this file to a release.
+        */}
+        <EmailLink href={actionUrl} style={brandColor ? { color: brandColor } : undefined}>
           {actionUrl}
         </EmailLink>
       </EmailText>

package/src/email/index.ts

@@ -1,3 +1,6 @@
 export { ActionEmail, type ActionEmailProps } from './ActionEmail';
 export { NoticeEmail, type NoticeEmailProps } from './NoticeEmail';
 export { EmailLayout, type EmailLayoutProps } from './EmailLayout';
+// Used internally by ActionEmail and useful on its own: any email with a button
+// wants a copyable link for the clients that strip them.
+export { EmailLinkFallback, type EmailLinkFallbackProps } from './EmailLinkFallback';

package/src/marketing/Footer.tsx

@@ -9,7 +9,13 @@ export interface FooterProps {
   navLinks?: Array<{ label: string; href: string }>;
   socialLinks?: Array<{ label: string; href: string; icon: ReactNode }>;
   legal?: string;
-  status?: { label: string; operational?: boolean };
+  /**
+   * Live status pill. `label` is a ReactNode, not a string: a real status
+   * pill often carries per-service detail in a tooltip, and typing it as
+   * string forced consumers to smuggle that through `as unknown as string`.
+   * A plain string still works and is the common case.
+   */
+  status?: { label: ReactNode; operational?: boolean };
   renderLink?: AppShellRenderLink;
 }