@letterncms/ui 0.0.0-stage → 0.1.0

package/src/ui/index.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @letterncms/ui — the admin theme's primitives: components, field editors and the small hooks
+ * every screen needs (shortcuts, color scheme, slugs). Shared with every module and plugin
+ * through the import map; screens themselves live in modules.
+ */
+export { cn } from './cn';
+export { Marquee } from './Marquee';
+export { SidebarRow } from './SidebarRow';
+export type { SidebarRowAction, SidebarRowProps } from './SidebarRow';
+export { Icon } from './Icon';
+export type { IconProps } from './Icon';
+export { Button, IconButton } from './Button';
+export type { ButtonProps, IconButtonProps, ButtonVariant, ButtonSize } from './Button';
+export { Spinner, Skeleton } from './Spinner';
+export { Input, Textarea } from './Input';
+export { Kbd } from './Kbd';
+export { Badge, StatusDot, statusLabel } from './Badge';
+export type { Tone } from './Badge';
+export { Avatar, AvatarStack } from './Avatar';
+export { Tooltip, TooltipProvider } from './Tooltip';
+export { Popover } from './Popover';
+export { Menu, MenuButton, ContextMenu } from './Menu';
+export type { MenuItemDef } from './Menu';
+export { Dialog, confirm, prompt } from './Dialog';
+export { Slideover } from './Slideover';
+export { InspectorPanel, useWideInspector } from './InspectorPanel';
+export { PersonPicker } from './PersonPicker';
+export { QueryError } from './QueryError';
+export { entryActionAvailability } from './entryActions';
+export { fieldControlId } from './fieldIdentity';
+export { Select } from './Select';
+export type { SelectOption } from './Select';
+export { Switch, Checkbox } from './Switch';
+export { Segmented, Tabs } from './Segmented';
+export { Field } from './Field';
+export { EmptyState } from './EmptyState';
+export { Page, Topbar, Section } from './Page';
+export type { Crumb } from './Page';
+export { List, Row } from './List';
+export { Widget, WidgetContext, useWidget, WidgetRow, WidgetMessage, WidgetSkeleton, Stat, Delta, Sparkline, Meter, BarRow, compactNumber } from './Widget';
+export type { WidgetMeta, WidgetProps, WidgetEmpty } from './Widget';
+export { Toaster, toast } from './toast';
+export { Fields } from './Fields';
+export type { FieldsProps } from './Fields';
+export { SortableTree } from './SortableTree';
+export type { SortableTreeProps, TreeItem } from './SortableTree';
+export { useShortcut } from './shortcuts';
+export { slugify } from './slugify';
+export { getThemePreference, setThemePreference } from './theme';
+export type { ThemePreference } from './theme';
+export { BlueprintEditor } from './BlueprintEditor';
+export type { BlueprintKind, BlueprintDefinition } from './BlueprintEditor';
+export { FieldsEditor } from '../fields/FieldsEditor';
+export type { RawField } from '../fields/FieldsEditor';
+export { DataTable, TableFrame, TableRow, TableHeader, TableSkeleton, TableToolbar } from './DataTable';
+export { DataView } from './DataView';
+export { DataCalendar } from './DataCalendar';
+export { calendarRange, calendarDayKey } from './calendar';
+export { useOverviewSource, loadOverviewSource } from './overviewSource';
+export type { OverviewSource } from './overviewSource';
+export { DateCell, longDate, shortDate, recordDateColumnIds, recordDateColumns, withRecordDateColumns } from './recordDates';
+export type { DataColumn, DataSelection } from './DataTable';
+export { DataGrid, DataCard } from './DataGrid';
+export { DisplayOptions, ViewSwitcher, OverviewControls, nextTableSort } from './ViewControls';
+export { readViewPrefs, useViewPrefs } from './viewPrefs';
+export type { ViewPrefs, ViewPrefsChange, CalendarDate } from './viewPrefs';
+export { entryFieldColumns, entrySystemColumns, fieldColumnId, standardEntryColumns } from './entryDisplay';
+export { SelectionBar } from './SelectionBar';
+export { PagePagination } from './PagePagination';
+export { useRecordNavigation } from './recordNavigation';
+export { WidgetSlot } from './WidgetSlot';
+export { Surface } from './SurfaceHost';

package/src/ui/overviewSource.d.ts

@@ -0,0 +1,16 @@
+import { type Page } from '@letterncms/sdk';
+/** Only source data varies by screen; loading every page belongs to the shared view. */
+export interface OverviewSource {
+    ability: string;
+    input?: Record<string, unknown>;
+    perPage?: number;
+}
+/** Preload the same first page used by the calendar, without duplicating query keys. */
+export declare function loadOverviewSource<T>(source: OverviewSource): Promise<Page<T>>;
+export declare function useOverviewSource<T>(source: OverviewSource | undefined, enabled: boolean): {
+    items: T[];
+    loading: boolean;
+    stale: boolean;
+    error: boolean;
+    retry: () => void;
+};

package/src/ui/recordDates.d.ts

@@ -0,0 +1,13 @@
+import { type RecordTimestamps } from '@letterncms/sdk';
+import type { DataColumn } from './DataTable';
+/** The same date formatting and metadata columns in every overview. */
+export declare const recordDateColumnIds: readonly ['published', 'updated'];
+export declare function shortDate(iso: string): string;
+export declare function longDate(iso: string): string;
+export declare function DateCell({ iso, relative }: {
+    iso: string | null | undefined;
+    relative?: boolean;
+}): import("react").JSX.Element;
+export declare function recordDateColumns<T>(dates: (item: T) => Partial<RecordTimestamps>, sort?: Partial<Record<'published' | 'updated', string>>): DataColumn<T>[];
+/** Called by DataView so new screens inherit the metadata without per-screen columns. */
+export declare function withRecordDateColumns<T>(columns: DataColumn<T>[], dates: (item: T) => Partial<RecordTimestamps>, sort?: Partial<Record<'published' | 'updated', string>>): DataColumn<T>[];

package/src/ui/recordNavigation.d.ts

@@ -0,0 +1,10 @@
+import { type RefObject } from 'react';
+import type { DataSelection } from './DataTable';
+/** Consistent j/k, x, Enter and Escape behavior in overview tables and cards. */
+export declare function useRecordNavigation<T>({ resetKey, onOpen, selection, enabled, scope }: {
+    scope?: RefObject<HTMLElement | null>;
+    resetKey: string;
+    onOpen?: (id: string) => void;
+    selection?: DataSelection<T>;
+    enabled?: boolean;
+}): string | null;

package/src/ui/shortcuts.d.ts

@@ -0,0 +1,4 @@
+/** Parse "mod+shift+k" and match a KeyboardEvent. Shift and Option change the character (⇧, gives <), so the key is matched by its position too. */
+export declare function matches(event: KeyboardEvent, combo: string): boolean;
+/** Global keyboard shortcut; ignores plain keys while typing. */
+export declare function useShortcut(combo: string, handler: (e: KeyboardEvent) => void, enabled?: boolean): void;

package/src/ui/slugify.d.ts

@@ -0,0 +1,2 @@
+/** A URL-safe slug from any text ("Über uns" → "uber-uns"). While typing, a trailing dash is kept. */
+export declare function slugify(value: string, typing?: boolean): string;

package/src/ui/theme.d.ts

@@ -0,0 +1,4 @@
+export type ThemePreference = 'light' | 'dark' | 'system';
+export declare function getThemePreference(): ThemePreference;
+export declare function setThemePreference(pref: ThemePreference): void;
+export declare function applyTheme(): void;

package/src/ui/toast.d.ts

@@ -0,0 +1,14 @@
+import { toast as sonner } from 'sonner';
+export declare function Toaster(): import("react").JSX.Element;
+/** Toasts. `toast.error(err)` accepts a CmsError and shows its message. */
+export declare const toast: ((message: string, options?: Parameters<typeof sonner>[1]) => string | number) & {
+    success: (message: string, options?: Parameters<typeof sonner.success>[1]) => string | number;
+    /** Pass `{ id }` to turn a loading toast into the error. */
+    error: (error: unknown, options?: string | {
+        id?: string | number;
+        fallback?: string;
+    }) => string | number;
+    loading: (message: string, options?: Parameters<typeof sonner.loading>[1]) => string | number;
+    promise: <T>(promise: Promise<T> | (() => Promise<T>), options?: Parameters<typeof sonner.promise<T>>[1]) => unknown;
+    dismiss: (id?: number | string) => string | number;
+};

package/src/ui/viewPrefs.d.ts

@@ -0,0 +1,17 @@
+import type { OverviewView as ListView } from './ViewControls';
+export type CalendarDate = 'published' | 'updated';
+export interface ViewPrefs {
+    view: ListView;
+    sort: string | null;
+    columns: string[] | null;
+    calendarDate: CalendarDate;
+}
+export type ViewPrefsChange = Partial<Omit<ViewPrefs, 'view'>> & {
+    view?: ListView | null;
+};
+export declare function readViewPrefs(handle: string, fallbackView?: ListView): ViewPrefs;
+/**
+ * View, sort and columns of an overview. Changes show at once and are saved
+ * to the account a moment later (one save for a burst of clicks).
+ */
+export declare function useViewPrefs(handle: string, fallbackView?: ListView): [ViewPrefs, (change: ViewPrefsChange) => void];

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.