@terrafirmagreg-team/ui 0.0.0-stage → 0.1.0

package/src/provider.tsx

@@ -0,0 +1,141 @@
+'use client';
+import Link from 'next/link';
+import {
+  createContext,
+  useContext,
+  useMemo,
+  type ComponentProps,
+  type ComponentType,
+  type ReactNode,
+} from 'react';
+import { flushSync } from 'react-dom';
+import { DirectionProvider } from '@base-ui/react/direction-provider';
+import {
+  ThemeProvider,
+  useTheme,
+  type ThemeProviderProps,
+} from 'next-themes';
+import { TranslationProvider } from '@terrafirmagreg-team/translate';
+import { useHotKey } from '@terrafirmagreg-team/ui/hooks/use-hot-key';
+
+export type UiLinkProps = { href: string; prefetch?: boolean } & Omit<
+  ComponentProps<'a'>,
+  'href'
+>;
+
+export type UiComponents = {
+  Link?: ComponentType<UiLinkProps>;
+};
+
+const defaults: Required<UiComponents> = {
+  Link: Link as ComponentType<UiLinkProps>,
+};
+
+const UiComponentsContext = createContext<UiComponents | null>(null);
+
+export function UiProvider({
+  components,
+  translations,
+  children,
+}: {
+  components?: UiComponents;
+  translations?: Record<string, string>;
+  children: ReactNode;
+}) {
+  const parent = useContext(UiComponentsContext);
+  const merged = useMemo(
+    () => ({ ...parent, ...components }),
+    [parent, components],
+  );
+  const inner = (
+    <UiComponentsContext.Provider value={merged}>
+      {children}
+    </UiComponentsContext.Provider>
+  );
+  if (!translations) return inner;
+  return (
+    <TranslationProvider translations={translations}>
+      {inner}
+    </TranslationProvider>
+  );
+}
+
+export function useUiComponents(): Required<UiComponents> {
+  return { ...defaults, ...useContext(UiComponentsContext) };
+}
+
+export interface ThemeOptions extends ThemeProviderProps {
+
+  enabled?: boolean;
+
+
+  hotKey?: string | ((e: KeyboardEvent) => boolean) | false;
+}
+
+
+function ThemeHotKey({
+  hotKey,
+}: {
+  hotKey: Exclude<ThemeOptions['hotKey'], false | undefined>;
+}) {
+  const { setTheme, resolvedTheme } = useTheme();
+
+  useHotKey(
+    (e) => {
+
+      const matched =
+        typeof hotKey === 'string'
+          ? !e.metaKey &&
+            !e.ctrlKey &&
+            !e.altKey &&
+            e.key.toLowerCase() === hotKey.toLowerCase()
+          : hotKey(e);
+      if (!matched) return;
+
+      e.preventDefault();
+      const next = resolvedTheme === 'dark' ? 'light' : 'dark';
+      if (document?.startViewTransition) {
+        document.startViewTransition(() => flushSync(() => setTheme(next)));
+      } else {
+        setTheme(next);
+      }
+    },
+    { ignoreTyping: true },
+  );
+
+  return null;
+}
+
+
+export function UiRootProvider({
+  children,
+  dir = 'ltr',
+  theme = {},
+}: {
+  children?: ReactNode;
+
+  dir?: 'rtl' | 'ltr';
+
+  theme?: ThemeOptions;
+}) {
+  let body = children;
+
+  if (theme?.enabled !== false) {
+    const { enabled: _, hotKey = 'd', ...themeProps } = theme;
+
+    body = (
+      <ThemeProvider
+        attribute="class"
+        defaultTheme="system"
+        enableSystem
+        disableTransitionOnChange
+        {...themeProps}
+      >
+        {hotKey !== false && <ThemeHotKey hotKey={hotKey} />}
+        {body}
+      </ThemeProvider>
+    );
+  }
+
+  return <DirectionProvider direction={dir}>{body}</DirectionProvider>;
+}

package/src/types/canvas.ts

@@ -0,0 +1,49 @@
+export type FlowPoint = { x: number; y: number };
+
+export type FlowRect = { x: number; y: number; width: number; height: number };
+
+export type FlowContentBox = {
+  midX: number;
+  midY: number;
+  width: number;
+  height: number;
+};
+
+export type FlowSizedNode = {
+  position: FlowPoint;
+  width?: number | null;
+  height?: number | null;
+};
+
+export type StoredViewport = { x: number; y: number; zoom: number };
+
+export type ChevronEdgeHighlight = 'incoming' | 'outgoing' | undefined;
+
+export type FlowHoverValue = {
+  id: string | null;
+  setId: (id: string | null) => void;
+};
+
+export type FlowCanvasViewport = {
+  storageKey: string;
+  resetKey: string;
+  selectedId?: string | null;
+
+  initFocusId?: string | null;
+  suppressPanRef?: { current: string | null };
+
+  userMovedRef?: { current: boolean };
+  focusZoom?: number;
+
+  minZoom?: number;
+  maxZoom?: number;
+  restoreViewport?: boolean;
+  ready?: boolean;
+
+  persist?: boolean;
+};
+
+export type FlowToolbarProps = {
+  onFit?: () => void;
+  search?: { label: string; onOpen: () => void };
+};

package/src/types/glb.ts

@@ -0,0 +1,25 @@
+import type { OrbitControls } from '@react-three/drei';
+import type { ComponentRef } from 'react';
+
+export type GlbOrbitControls = ComponentRef<typeof OrbitControls>;
+
+export type GlbHomeView = {
+  position: [number, number, number];
+  target: [number, number, number];
+};
+
+export type GlbSceneHandle = {
+  zoomBy: (factor: number) => void;
+  reset: () => void;
+};
+
+export type GlbSessionProps = {
+  src?: string | null;
+  sources?: string[];
+  title?: string;
+  scale?: number;
+  offset?: number;
+  bare?: boolean;
+
+  resolveResource?: (resourceUrl: string, modelUrl: string) => string | undefined;
+};

package/src/types/nav.ts

@@ -0,0 +1,95 @@
+import type { ComponentProps, ReactNode } from 'react';
+
+export type SwitcherOption = {
+  value: string;
+  title: ReactNode;
+  description?: ReactNode;
+  icon?: ReactNode;
+  url?: string;
+  disabled?: boolean;
+};
+
+export type SwitcherProps = Omit<ComponentProps<'button'>, 'onSelect'> & {
+  options: SwitcherOption[];
+  selected?: string;
+  onSelect?: (value: string) => void;
+  placeholder?: ReactNode;
+  icon?: ReactNode;
+  header?: ReactNode;
+  side?: 'top' | 'bottom' | 'left' | 'right';
+};
+
+export type LinkProps = ComponentProps<'a'> & {
+  href?: string;
+  external?: boolean;
+  prefetch?: boolean;
+  children?: ReactNode;
+};
+
+interface Filterable {
+
+  on?: 'menu' | 'nav' | 'all';
+}
+
+interface WithHref {
+  url: string;
+
+  active?: 'url' | 'nested-url' | 'none';
+  external?: boolean;
+}
+
+export interface MainItemType extends WithHref, Filterable {
+  type?: 'main';
+  icon?: ReactNode;
+  text: ReactNode;
+  description?: ReactNode;
+}
+
+export interface IconItemType extends WithHref, Filterable {
+  type: 'icon';
+
+  label?: string;
+  icon: ReactNode;
+  text: ReactNode;
+
+  secondary?: boolean;
+}
+
+export interface ButtonItemType extends WithHref, Filterable {
+  type: 'button';
+  icon?: ReactNode;
+  text: ReactNode;
+
+  secondary?: boolean;
+}
+
+export interface MenuItemType extends Partial<WithHref>, Filterable {
+  type: 'menu';
+  icon?: ReactNode;
+  text: ReactNode;
+  items: (
+    | (MainItemType & {
+
+        menu?: ComponentProps<'a'> & {
+          banner?: ReactNode;
+        };
+      })
+    | CustomItemType
+  )[];
+
+  secondary?: boolean;
+}
+
+export interface CustomItemType extends Filterable {
+  type: 'custom';
+
+  secondary?: boolean;
+  children: ReactNode;
+}
+
+export type LinkItemType =
+  | MainItemType
+  | IconItemType
+  | ButtonItemType
+  | MenuItemType
+  | CustomItemType;

package/src/types/preview.ts

@@ -0,0 +1,9 @@
+export type PreviewIcon =
+  | { type: 'icon'; name: string }
+  | { type: 'entry'; kind: string; id: string; dataset?: string };
+
+export type PagePreviewData = {
+  title: string;
+  description?: string;
+  icon?: PreviewIcon;
+};

package/src/types/readability.ts

@@ -0,0 +1,28 @@
+export const readabilityLayouts = [
+  'full',
+  'sidebar',
+  'both',
+  'original',
+] as const;
+export type ReadabilityLayout = (typeof readabilityLayouts)[number];
+
+export const spotlightStyles = ['under', 'aside'] as const;
+export type SpotlightStyle = (typeof spotlightStyles)[number];
+
+export type ReadabilityState = {
+  layout: ReadabilityLayout;
+  pageWidth: number;
+  contentWidth: number;
+  spotlight: boolean;
+  spotlightStyle: SpotlightStyle;
+};
+
+export type ReadabilityValue = ReadabilityState & {
+  coarsePointer: boolean;
+  smallScreen: boolean;
+  setLayout: (layout: ReadabilityLayout) => void;
+  setPageWidth: (value: number) => void;
+  setContentWidth: (value: number) => void;
+  setSpotlight: (enabled: boolean) => void;
+  setSpotlightStyle: (style: SpotlightStyle) => void;
+};

package/src/types/search.ts

@@ -0,0 +1,56 @@
+import type { Dialog } from '@base-ui/react/dialog';
+import type { Root } from 'hast';
+import type { ReactNode } from 'react';
+
+export interface SharedProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  dialogHandle: Dialog.Handle<unknown>;
+}
+
+export interface SortedResult<Content = string> {
+  id: string;
+  url: string;
+  type: 'page' | 'heading' | 'text';
+  content: Content;
+
+  breadcrumbs?: Content[];
+
+  table?: string;
+}
+
+export type ReactSortedResult = SortedResult<ReactNode>;
+
+export interface SearchResultRecord extends SortedResult {
+
+  hastContent: Root;
+}
+
+export interface SearchResultTable {
+  type: 'table';
+
+  id: string;
+  columns: number;
+
+  header?: Root;
+  rows: SearchResultRecord[];
+}
+
+export type SearchResultItem = SearchResultRecord | SearchResultTable;
+
+export interface SearchResult {
+
+  query: string;
+  items: SearchResultItem[];
+}
+
+export type SearchItemType =
+  | ((ReactSortedResult | SearchResultRecord) & {
+      external?: boolean;
+    })
+  | {
+      id: string;
+      type: 'action';
+      node: ReactNode;
+      onSelect: () => void;
+    };

package/src/types/tree.ts

@@ -0,0 +1,18 @@
+import type * as PageTree from '@terrafirmagreg-team/translate/types/tree';
+import type { ReactNode } from 'react';
+
+export interface TreeContextValue {
+
+  root: PageTree.Root | PageTree.Folder;
+  full: PageTree.Root;
+}
+
+export interface TabOption {
+  url: string;
+  title?: ReactNode;
+  icon?: ReactNode;
+  description?: ReactNode;
+  unlisted?: boolean;
+  $folder?: PageTree.Folder;
+  urls?: Set<string>;
+}

package/src/types/viewer.ts

@@ -0,0 +1,53 @@
+import type { ReactNode, RefObject } from 'react';
+
+export type ZoomControlsProps = {
+  onZoomIn: () => void;
+  onZoomOut: () => void;
+  onFit?: () => void;
+  fitLabel?: string;
+};
+
+export type PagerControlsProps = {
+  index: number;
+  count: number;
+  onSelect: (index: number) => void;
+};
+
+export type ExpandButtonProps = {
+  target: RefObject<HTMLElement | null>;
+};
+
+export type ViewerSliderSetting = {
+  label: ReactNode;
+  icon?: ReactNode;
+  value: number;
+  onChange: (value: number) => void;
+  min?: number;
+  max?: number;
+  step?: number;
+  format?: (value: number) => string;
+  disabled?: boolean;
+  live?: boolean;
+};
+
+export type ViewerToggleSetting = {
+  label: ReactNode;
+  icon?: ReactNode;
+  checked: boolean;
+  onChange: (value: boolean) => void;
+};
+
+export type ViewerSettingsProps = {
+  label: string;
+  sliders?: ViewerSliderSetting[];
+  toggles?: ViewerToggleSetting[];
+};
+
+export type ViewerControlsProps = {
+  start?: ReactNode;
+  pager?: PagerControlsProps;
+  zoom?: ZoomControlsProps;
+  expand?: ExpandButtonProps;
+  extra?: ReactNode;
+  settings?: ViewerSettingsProps;
+};

package/styles/content/base.css

@@ -0,0 +1,194 @@
+:root {
+  --sidebar-drawer-offset: 100%;
+}
+
+[dir='rtl'] {
+  --sidebar-drawer-offset: -100%;
+}
+
+@theme {
+  --animate-fade-in: fade-in 300ms ease;
+  --animate-fade-out: fade-out 300ms ease;
+
+  /* slide in from below, or from above when `--roll` is -1 */
+  --animate-roll-in: roll-in 320ms cubic-bezier(0.22, 1, 0.36, 1);
+
+  --animate-dialog-in: dialog-in 300ms cubic-bezier(0.16, 1, 0.3, 1);
+  --animate-dialog-out: dialog-out 300ms cubic-bezier(0.16, 1, 0.3, 1);
+
+  --animate-popover-in: popover-in 100ms ease;
+  --animate-popover-out: popover-out 100ms ease;
+
+  --animate-sidebar-in: sidebar-in 250ms ease;
+  --animate-sidebar-out: sidebar-out 250ms ease;
+
+  @keyframes sidebar-in {
+    from {
+      transform: translateX(var(--sidebar-drawer-offset));
+    }
+  }
+
+  @keyframes sidebar-out {
+    to {
+      transform: translateX(var(--sidebar-drawer-offset));
+    }
+  }
+
+  @keyframes dialog-in {
+    from {
+      transform: scale(1.06);
+      opacity: 0;
+    }
+    to {
+      transform: scale(1);
+    }
+  }
+
+  @keyframes dialog-out {
+    from {
+      transform: scale(1);
+    }
+    to {
+      transform: scale(1.04);
+      opacity: 0;
+    }
+  }
+
+  @keyframes popover-in {
+    from {
+      opacity: 0;
+      transform: scale(0.9);
+    }
+  }
+
+  @keyframes popover-out {
+    to {
+      opacity: 0;
+      transform: scale(0.9);
+    }
+  }
+
+  @keyframes fade-in {
+    from {
+      opacity: 0;
+    }
+    to {
+      opacity: 1;
+    }
+  }
+
+  @keyframes roll-in {
+    from {
+      opacity: 0;
+      translate: 0 calc(var(--roll, 1) * 0.6em);
+      filter: blur(2px);
+    }
+  }
+
+  @keyframes fade-out {
+    from {
+      opacity: 1;
+    }
+    to {
+      opacity: 0;
+    }
+  }
+}
+
+@layer base {
+  *,
+  ::after,
+  ::before,
+  ::backdrop,
+  ::file-selector-button {
+    border-color: var(--color-border, currentColor);
+  }
+
+  body {
+    background-color: var(--color-background);
+    color: var(--color-foreground);
+  }
+}
+
+@utility scroll-container {
+  &::-webkit-scrollbar {
+    width: 5px;
+    height: 5px;
+  }
+
+  &::-webkit-scrollbar-thumb {
+    border-radius: 5px;
+    background: var(--color-border);
+  }
+
+  &::-webkit-scrollbar-track {
+    background: transparent;
+  }
+
+  &::-webkit-scrollbar-corner {
+    display: none;
+  }
+}
+
+@utility fd-steps {
+  counter-reset: step;
+  position: relative;
+  @apply ps-6 ms-2 border-s sm:ms-4 sm:ps-7;
+}
+
+@utility fd-step {
+  &:before {
+    background-color: var(--color-secondary);
+    color: var(--color-secondary-foreground);
+    content: counter(step);
+    counter-increment: step;
+    justify-content: center;
+    align-items: center;
+    font-size: 0.875rem;
+    line-height: 1.25rem;
+    display: flex;
+    position: absolute;
+    @apply size-8 -inset-s-4 rounded-full;
+  }
+}
+
+@utility prose-no-margin {
+  & > :first-child {
+    margin-top: 0;
+  }
+
+  & > :last-child {
+    margin-bottom: 0;
+  }
+}
+
+@variant dark (&:where(.dark, .dark *));
+
+/* define/override layout variables */
+@variant layout {
+  #docs-layout:has(&),
+  #notebook-layout:has(&),
+  #home-layout:has(&),
+  #flux-layout:has(&),
+  #glass-layout:has(&),
+  #spacious-layout:has(&) {
+    @slot;
+  }
+}
+
+/* to transition the columns alone */
+@property --sidebar-col {
+  syntax: '<length>';
+  inherits: true;
+  initial-value: 0px;
+}
+
+@property --ai-chat-col {
+  syntax: '<length>';
+  inherits: true;
+  initial-value: 0px;
+}
+
+.fd-page-tree-item-name {
+  @apply inline-flex items-center gap-1 w-full;
+}