@olwiba/ui 0.2.5 → 0.2.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olwiba/ui",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "private": false,
   "type": "module",
   "sideEffects": false,

package/src/app/AppShell.tsx

@@ -110,6 +110,15 @@ export interface AppShellProps {
   sidebarPosition?: 'viewport' | 'contained';
   /** Which side the sidebar sits on. @default "left" */
   side?: 'left' | 'right';
+  /**
+   * Class applied to the content wrapper around `children`, between the
+   * header and the page content. Every consuming page otherwise has to
+   * remember its own padding — some do, some don't, and the ones that don't
+   * end up flush against the sidebar/header chrome. Override to `''` for a
+   * genuinely edge-to-edge page (a full-width table, a map/canvas).
+   * @default "p-6"
+   */
+  contentClassName?: string;
 }
 
 // ─── Internal sub-components ──────────────────────────────────────────────────
@@ -377,6 +386,7 @@ export function AppShell({
   collapsible = 'icon',
   sidebarPosition = 'viewport',
   side = 'left',
+  contentClassName = 'p-6',
   children,
 }: AppShellProps = {}) {
   const isContained = sidebarPosition === 'contained';
@@ -398,7 +408,7 @@ export function AppShell({
       />
       <SidebarInset className={isContained ? undefined : 'overflow-y-auto'}>
         <ShellHeader pageTitle={pageTitle} headerStart={headerStart} headerEnd={headerEnd} />
-        {children}
+        <div className={contentClassName}>{children}</div>
       </SidebarInset>
     </SidebarProvider>
   );

package/src/app/DataView.tsx

@@ -0,0 +1,99 @@
+'use client';
+
+import * as React from 'react';
+import type { ColumnDef } from '@tanstack/react-table';
+import { cn } from '@olwiba/cn';
+import { AppGrid, type AppGridColumns } from '../layout/AppGrid';
+import { DataTable } from '../components/DataTable';
+import type { ViewMode } from '../hooks/use-view-mode';
+
+export interface DataViewProps<TData> {
+  items: TData[];
+  /** Stable key per item. */
+  getRowId: (item: TData) => string;
+  /** Card renderer for the grid view. */
+  renderCard: (item: TData) => React.ReactNode;
+  /** Columns for the list view. */
+  columns: ColumnDef<TData>[];
+  view: ViewMode;
+  /**
+   * False while a persisted preference is still being read. The whole view is
+   * withheld until true — see the note on the component.
+   */
+  ready?: boolean;
+  /** Grid density at the widest breakpoint. Default 3. */
+  gridColumns?: AppGridColumns;
+  gap?: 'none' | 'sm' | 'md' | 'lg';
+  /** Rendered instead of either view when there is nothing to show. */
+  empty?: React.ReactNode;
+  /** Shown while `ready` is false. Defaults to nothing. */
+  placeholder?: React.ReactNode;
+  searchKey?: string;
+  searchPlaceholder?: string;
+  pageSize?: number;
+  emptyMessage?: string;
+  onRowClick?: (row: TData) => void;
+  className?: string;
+}
+
+/**
+ * A collection rendered either as a grid of cards or as a table, from one set
+ * of data.
+ *
+ * Knows nothing about what it is listing: callers supply a card renderer and
+ * table columns. Cards are for "what arrived recently", the table for
+ * comparing many rows at once, and switching between them should not mean two
+ * page implementations that drift apart.
+ *
+ * The `ready` gate is the subtle part, and the reason this is a component
+ * rather than a snippet to copy. A persisted preference cannot be read during
+ * SSR or the first client render, so a page that renders its default
+ * immediately will either mismatch on hydration or visibly flash the wrong
+ * view at anyone who chose the other one. Holding the section until the
+ * preference resolves avoids both, and putting that here means no consumer
+ * has to work it out again.
+ */
+export function DataView<TData>({
+  items,
+  getRowId,
+  renderCard,
+  columns,
+  view,
+  ready = true,
+  gridColumns = 3,
+  gap = 'sm',
+  empty,
+  placeholder = null,
+  searchKey,
+  searchPlaceholder,
+  pageSize = 25,
+  emptyMessage,
+  onRowClick,
+  className,
+}: DataViewProps<TData>) {
+  if (!ready) return <>{placeholder}</>;
+  if (items.length === 0 && empty) return <>{empty}</>;
+
+  if (view === 'list') {
+    return (
+      <DataTable
+        columns={columns}
+        data={items}
+        searchKey={searchKey}
+        searchPlaceholder={searchPlaceholder}
+        pageSize={pageSize}
+        emptyMessage={emptyMessage}
+        onRowClick={onRowClick}
+        className={className}
+      />
+    );
+  }
+
+  return (
+    <AppGrid columns={gridColumns} gap={gap} className={cn(className)}>
+      {items.map((item) => (
+        <React.Fragment key={getRowId(item)}>{renderCard(item)}</React.Fragment>
+      ))}
+    </AppGrid>
+  );
+}

package/src/components/MediaCard.tsx

@@ -0,0 +1,68 @@
+'use client';
+
+import * as React from 'react';
+import { Card, cn } from '@olwiba/cn';
+
+const bannerAspectClass = {
+  wide: 'aspect-[3/1]',
+  video: 'aspect-video',
+  square: 'aspect-square',
+};
+
+export interface MediaCardProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * Banner rendered above the content, clipped to the card's rounded corners.
+   * A ReactNode rather than a src, so a brand fallback, an inline SVG, a map,
+   * or a plain <img> all work — this is the difference from ImageCard, which
+   * takes a URL and is the right choice when you actually have one.
+   */
+  banner?: React.ReactNode;
+  /** Banner proportions. Default 'wide' (3:1), which suits a header strip. */
+  bannerAspect?: keyof typeof bannerAspectClass;
+  /**
+   * Pinned to the bottom of the card. In a grid this is what keeps the
+   * primary action on a shared baseline across a row, however unevenly the
+   * titles above it wrap.
+   */
+  footer?: React.ReactNode;
+  children?: React.ReactNode;
+}
+
+/**
+ * A Card with an optional banner and a bottom-pinned footer.
+ *
+ * Deliberately knows nothing about what it is showing — the domain-shaped
+ * cards (a property, a monitor, an article) compose this and supply their own
+ * content. It exists because "banner, then content, then an action pinned to
+ * the bottom, all the same height across a row" was being hand-rolled per
+ * product, and the equal-height part in particular is easy to get subtly
+ * wrong.
+ *
+ * `h-full` is on the card itself so a bare `<MediaCard>` inside a grid cell
+ * fills that cell without every caller remembering to ask.
+ */
+export function MediaCard({
+  banner,
+  bannerAspect = 'wide',
+  footer,
+  children,
+  className,
+  ...props
+}: MediaCardProps) {
+  return (
+    <Card
+      className={cn('flex h-full w-full flex-col overflow-hidden', banner && 'pt-0', className)}
+      {...props}
+    >
+      {banner && (
+        <div className={cn('w-full shrink-0 overflow-hidden', bannerAspectClass[bannerAspect])}>
+          {banner}
+        </div>
+      )}
+      <div className="flex flex-1 flex-col gap-3 p-4">
+        {children}
+        {footer && <div className="mt-auto pt-1">{footer}</div>}
+      </div>
+    </Card>
+  );
+}

package/src/components/ViewToggle.tsx

@@ -0,0 +1,47 @@
+'use client';
+
+import * as React from 'react';
+import { Button, cn } from '@olwiba/cn';
+import { LayoutGrid, List } from 'lucide-react';
+import type { ViewMode } from '../hooks/use-view-mode';
+
+export interface ViewToggleProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange'> {
+  view: ViewMode;
+  onChange: (view: ViewMode) => void;
+  labels?: { cards?: string; list?: string };
+}
+
+/**
+ * Two-state segmented control for switching a collection between cards and a
+ * list. Controlled — pair it with useViewMode to persist the choice.
+ */
+export function ViewToggle({ view, onChange, labels, className, ...props }: ViewToggleProps) {
+  const options = [
+    { mode: 'cards' as const, label: labels?.cards ?? 'Card view', Icon: LayoutGrid },
+    { mode: 'list' as const, label: labels?.list ?? 'List view', Icon: List },
+  ];
+
+  return (
+    <div
+      className={cn('inline-flex items-center rounded-md border p-0.5', className)}
+      role="group"
+      aria-label="View mode"
+      {...props}
+    >
+      {options.map(({ mode, label, Icon }) => (
+        <Button
+          key={mode}
+          type="button"
+          size="sm"
+          variant={view === mode ? 'secondary' : 'ghost'}
+          className="h-7 px-2"
+          aria-label={label}
+          aria-pressed={view === mode}
+          onClick={() => onChange(mode)}
+        >
+          <Icon className="size-4" />
+        </Button>
+      ))}
+    </div>
+  );
+}

package/src/hooks/use-view-mode.ts

@@ -0,0 +1,36 @@
+'use client';
+
+import { useLocalStorage } from './use-local-storage';
+import { useMounted } from './use-mounted';
+
+export type ViewMode = 'cards' | 'list';
+
+export interface UseViewModeReturn {
+  view: ViewMode;
+  setView: (view: ViewMode) => void;
+  /**
+   * False until the stored preference is readable. Render a skeleton or hold
+   * the section until this is true — see the note below on why.
+   */
+  ready: boolean;
+}
+
+/**
+ * Remembered cards/list preference.
+ *
+ * Returns the fallback on the server and on the first client render, then
+ * settles to the stored value once mounted. Returning the stored value
+ * immediately would have the server emit card markup while the client builds
+ * a table — a hydration mismatch — and painting the fallback first flashes
+ * the wrong view at someone who chose the other one. `ready` lets callers
+ * wait for the real answer instead of doing either.
+ *
+ * The key is shared by default so the choice reads as one product-wide
+ * preference: pick list on one page and every page follows. Pass a distinct
+ * key where a page genuinely wants its own.
+ */
+export function useViewMode(key = 'view-mode', fallback: ViewMode = 'cards'): UseViewModeReturn {
+  const [stored, setStored] = useLocalStorage<ViewMode>(key, fallback);
+  const mounted = useMounted();
+  return { view: mounted ? stored : fallback, setView: setStored, ready: mounted };
+}

package/src/index.ts

@@ -128,6 +128,7 @@ export { CommandMenu, type CommandMenuProps, type CommandMenuGroup, type Command
 
 // ─── Components — data ───────────────────────────────────────────────────────
 export { DataTable, type DataTableProps, type DataTableColumn } from './components/DataTable';
+export { DataView, type DataViewProps } from './app/DataView';
 export { Chart, type ChartProps, type ChartSeries } from './components/Chart';
 export { FileUpload, type FileUploadProps, type FileUploadEntry } from './components/FileUpload';
 
@@ -147,6 +148,8 @@ export { StatCard, type StatCardProps } from './components/StatCard';
 export { TestimonialCard, type TestimonialCardProps } from './components/TestimonialCard';
 export { PricingCard, type PricingCardProps, type PricingFeature } from './components/PricingCard';
 export { ImageCard, type ImageCardProps } from './components/ImageCard';
+export { MediaCard, type MediaCardProps } from './components/MediaCard';
+export { ViewToggle, type ViewToggleProps } from './components/ViewToggle';
 
 // ─── Components — diagram ────────────────────────────────────────────────────
 export { FlowConnector, type FlowConnectorProps } from './components/FlowConnector';
@@ -183,5 +186,6 @@ export { useCopyToClipboard } from './hooks/use-copy-to-clipboard';
 export { useDebounce } from './hooks/use-debounce';
 export { useIntersectionObserver } from './hooks/use-intersection-observer';
 export { useLocalStorage } from './hooks/use-local-storage';
+export { useViewMode, type ViewMode, type UseViewModeReturn } from './hooks/use-view-mode';
 export { useMediaQuery } from './hooks/use-media-query';
 export { usePagination, type UsePaginationReturn } from './hooks/use-pagination';

package/src/layout/AppGrid.tsx

@@ -1,29 +1,48 @@
 import React from 'react'
 import { cn } from '../lib/utils'
 
+/**
+ * Responsive ramps per column count. Every ramp starts at a single column —
+ * a card grid that stays multi-column on a phone is unreadable — and adds
+ * columns at breakpoints wide enough to keep each card legible.
+ *
+ * Written out in full rather than composed, because Tailwind scans source for
+ * complete class strings; a template literal like `xl:grid-cols-${n}` produces
+ * nothing at build time.
+ */
 const columnsMap = {
   1: 'grid-cols-1',
-  2: 'grid-cols-1 md:grid-cols-2',
-  3: 'grid-cols-1 md:grid-cols-2 xl:grid-cols-3',
-  4: 'grid-cols-1 md:grid-cols-2 xl:grid-cols-4',
+  2: 'grid-cols-1 sm:grid-cols-2',
+  3: 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-3',
+  4: 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4',
+  5: 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-5',
+  6: 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-6',
 }
 
 const gapMap = {
+  none: 'gap-0',
   sm: 'gap-3',
   md: 'gap-4',
   lg: 'gap-6',
 }
 
 const spanMap = {
-  1: 'md:col-span-1',
-  2: 'md:col-span-2',
-  3: 'xl:col-span-3',
+  1: 'sm:col-span-1',
+  2: 'sm:col-span-2',
+  3: 'lg:col-span-3',
   4: 'xl:col-span-4',
   full: 'col-span-full',
 }
 
+export type AppGridColumns = keyof typeof columnsMap
+
 export interface AppGridProps extends React.HTMLAttributes<HTMLDivElement> {
-  columns?: keyof typeof columnsMap
+  /**
+   * Columns at the widest breakpoint. Narrower screens step down through the
+   * ramp automatically, so this is "how dense at full width", not a fixed
+   * count. Default 3.
+   */
+  columns?: AppGridColumns
   gap?: keyof typeof gapMap
 }
 

package/src/layout/index.ts

@@ -7,6 +7,6 @@ export type { SectionProps } from './Section'
 export { AppContent } from './AppContent'
 export type { AppContentProps } from './AppContent'
 export { AppGrid, AppGridCell } from './AppGrid'
-export type { AppGridProps, AppGridCellProps } from './AppGrid'
+export type { AppGridProps, AppGridCellProps, AppGridColumns } from './AppGrid'
 export { PublicPageFrame } from './PublicPageFrame'
 export type { PublicPageFrameProps } from './PublicPageFrame'

package/src/marketing/Navbar.tsx

@@ -31,6 +31,7 @@ export function Navbar({
   const [open, setOpen] = React.useState(false);
   const brandHref = brand.href ?? '/';
   const hasRightContent = controls?.length || cta?.primary || cta?.secondary;
+  const closeMobileMenu = React.useCallback(() => setOpen(false), []);
 
   return (
     <section className="overflow-hidden rounded-2xl border bg-card">
@@ -92,7 +93,7 @@ export function Navbar({
           <SheetContent side="left" className="w-72">
             {/* Brand row alone at the top — leaves the top-right corner to the built-in close */}
             <div className="flex items-center pb-4">
-              <span onClick={() => setOpen(false)} className="cursor-pointer">
+              <span onClickCapture={closeMobileMenu} className="cursor-pointer">
                 {renderLink({
                   href: brandHref,
                   children: (
@@ -114,7 +115,7 @@ export function Navbar({
             <Separator />
             <nav className="mt-4 flex flex-col gap-1">
               {navLinks.map((link) => (
-                <span key={link.label} onClick={() => setOpen(false)}>
+                <span key={link.label} onClickCapture={closeMobileMenu}>
                   {renderLink({
                     href: link.href,
                     className: 'block rounded-md px-3 py-2 text-sm text-muted-foreground transition-colors hover:bg-accent hover:text-accent-foreground',
@@ -124,16 +125,22 @@ export function Navbar({
               ))}
             </nav>
             <div className="mt-6 flex flex-col gap-2">
-              {cta?.secondary &&
-                renderLink({
-                  href: cta.secondary.href,
-                  children: <Button variant="outline" className="w-full">{cta.secondary.label}</Button>,
-                })}
-              {cta?.primary &&
-                renderLink({
-                  href: cta.primary.href,
-                  children: <Button className="w-full">{cta.primary.label}</Button>,
-                })}
+              {cta?.secondary && (
+                <span onClickCapture={closeMobileMenu}>
+                  {renderLink({
+                    href: cta.secondary.href,
+                    children: <Button variant="outline" className="w-full">{cta.secondary.label}</Button>,
+                  })}
+                </span>
+              )}
+              {cta?.primary && (
+                <span onClickCapture={closeMobileMenu}>
+                  {renderLink({
+                    href: cta.primary.href,
+                    children: <Button className="w-full">{cta.primary.label}</Button>,
+                  })}
+                </span>
+              )}
             </div>
           </SheetContent>
         </Sheet>