@fragments-sdk/cli 0.7.10 → 0.7.12

package/src/viewer/vendor/shared/src/DocsPageShell.tsx

@@ -0,0 +1,119 @@
+'use client';
+
+import { AppShell } from '@fragments-sdk/ui';
+import type { ReactNode } from 'react';
+import { DocsPageAsideHost, DocsPageAsideProvider, useDocsPageAside } from './DocsPageAsideHost';
+
+type SidebarCollapsible = 'offcanvas' | 'icon' | 'none';
+
+interface DocsPageShellProps {
+  header: ReactNode;
+  sidebar: ReactNode;
+  children: ReactNode;
+  sidebarWidth?: string;
+  sidebarCollapsible?: SidebarCollapsible;
+  sidebarAriaLabel?: string;
+  mainId?: string;
+  mainAriaLabel?: string;
+  mainPadding?: 'none' | 'sm' | 'md' | 'lg';
+  mainClassName?: string;
+  aside?: ReactNode;
+  asideWidth?: string;
+  useAsidePortal?: boolean;
+}
+
+function DocsPageShellInner({
+  header,
+  sidebar,
+  children,
+  sidebarWidth = '260px',
+  sidebarCollapsible = 'offcanvas',
+  sidebarAriaLabel = 'Documentation sidebar',
+  mainId = 'main-content',
+  mainAriaLabel = 'Documentation content',
+  mainPadding = 'lg',
+  mainClassName,
+  aside,
+  asideWidth = '320px',
+  useAsidePortal = false,
+}: DocsPageShellProps) {
+  return (
+    <AppShell>
+      <AppShell.Header>{header}</AppShell.Header>
+
+      <AppShell.Sidebar
+        width={sidebarWidth}
+        collapsible={sidebarCollapsible}
+        aria-label={sidebarAriaLabel}
+      >
+        {sidebar}
+      </AppShell.Sidebar>
+
+      <AppShell.Main
+        id={mainId}
+        aria-label={mainAriaLabel}
+        padding={mainPadding}
+        className={mainClassName}
+      >
+        {children}
+      </AppShell.Main>
+
+      {useAsidePortal ? <DocsPageAsideHost /> : null}
+      {!useAsidePortal && aside ? <AppShell.Aside width={asideWidth}>{aside}</AppShell.Aside> : null}
+    </AppShell>
+  );
+}
+
+function DocsPageShellPortalInner({
+  header,
+  sidebar,
+  children,
+  sidebarWidth = '260px',
+  sidebarCollapsible = 'offcanvas',
+  sidebarAriaLabel = 'Documentation sidebar',
+  mainId = 'main-content',
+  mainAriaLabel = 'Documentation content',
+  mainPadding = 'lg',
+  mainClassName,
+}: DocsPageShellProps) {
+  const { asideVisible, asideWidth } = useDocsPageAside();
+
+  return (
+    <AppShell>
+      <AppShell.Header>{header}</AppShell.Header>
+
+      <AppShell.Sidebar
+        width={sidebarWidth}
+        collapsible={sidebarCollapsible}
+        aria-label={sidebarAriaLabel}
+      >
+        {sidebar}
+      </AppShell.Sidebar>
+
+      <AppShell.Main
+        id={mainId}
+        aria-label={mainAriaLabel}
+        padding={mainPadding}
+        className={mainClassName}
+      >
+        {children}
+      </AppShell.Main>
+
+      <AppShell.Aside width={asideWidth} visible={asideVisible} aria-label="On-page controls">
+        <DocsPageAsideHost />
+      </AppShell.Aside>
+    </AppShell>
+  );
+}
+
+export function DocsPageShell(props: DocsPageShellProps) {
+  if (props.useAsidePortal) {
+    return (
+      <DocsPageAsideProvider defaultWidth={props.asideWidth}>
+        <DocsPageShellPortalInner {...props} />
+      </DocsPageAsideProvider>
+    );
+  }
+
+  return <DocsPageShellInner {...props} />;
+}

package/src/viewer/vendor/shared/src/DocsSearchCommand.tsx

@@ -0,0 +1,134 @@
+'use client';
+
+import { Input, Listbox } from '@fragments-sdk/ui';
+import { useEffect, useMemo, useRef, useState, type KeyboardEvent as ReactKeyboardEvent } from 'react';
+import type { SearchItem } from './types';
+
+interface DocsSearchCommandProps {
+  searchItems: SearchItem[];
+  onSelect: (item: SearchItem) => void;
+  placeholder?: string;
+  maxResults?: number;
+}
+
+export function DocsSearchCommand({
+  searchItems,
+  onSelect,
+  placeholder = 'Search...',
+  maxResults = 8,
+}: DocsSearchCommandProps) {
+  const [query, setQuery] = useState('');
+  const [isOpen, setIsOpen] = useState(false);
+  const [selectedIndex, setSelectedIndex] = useState(0);
+  const inputRef = useRef<HTMLInputElement>(null);
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  const results = useMemo(() => {
+    if (!query.trim()) return [];
+    const lowerQuery = query.toLowerCase();
+    return searchItems
+      .filter((item) => item.label.toLowerCase().includes(lowerQuery) || item.section.toLowerCase().includes(lowerQuery))
+      .slice(0, maxResults);
+  }, [maxResults, query, searchItems]);
+
+  useEffect(() => {
+    setSelectedIndex(0);
+  }, [results]);
+
+  useEffect(() => {
+    const handleGlobalKeyDown = (event: KeyboardEvent) => {
+      if ((event.metaKey || event.ctrlKey) && event.key === 'k') {
+        event.preventDefault();
+        inputRef.current?.focus();
+        setIsOpen(true);
+      }
+    };
+
+    document.addEventListener('keydown', handleGlobalKeyDown);
+    return () => document.removeEventListener('keydown', handleGlobalKeyDown);
+  }, []);
+
+  useEffect(() => {
+    const handleClickOutside = (event: MouseEvent) => {
+      if (containerRef.current && !containerRef.current.contains(event.target as Node)) {
+        setIsOpen(false);
+      }
+    };
+
+    document.addEventListener('mousedown', handleClickOutside);
+    return () => document.removeEventListener('mousedown', handleClickOutside);
+  }, []);
+
+  const handleSelect = (item: SearchItem) => {
+    onSelect(item);
+    setIsOpen(false);
+    setQuery('');
+  };
+
+  const handleKeyDown = (event: ReactKeyboardEvent) => {
+    if (!isOpen || results.length === 0) return;
+
+    switch (event.key) {
+      case 'ArrowDown':
+        event.preventDefault();
+        setSelectedIndex((prev) => (prev + 1) % results.length);
+        break;
+      case 'ArrowUp':
+        event.preventDefault();
+        setSelectedIndex((prev) => (prev - 1 + results.length) % results.length);
+        break;
+      case 'Enter':
+        event.preventDefault();
+        if (results[selectedIndex]) {
+          handleSelect(results[selectedIndex]);
+          inputRef.current?.blur();
+        }
+        break;
+      case 'Escape':
+        setIsOpen(false);
+        inputRef.current?.blur();
+        break;
+      default:
+        break;
+    }
+  };
+
+  return (
+    <div ref={containerRef} className="shared-docs-search-container">
+      <Input
+        ref={inputRef}
+        placeholder={placeholder}
+        aria-label="Search"
+        value={query}
+        onChange={(value) => {
+          setQuery(value);
+          setIsOpen(true);
+        }}
+        onFocus={() => setIsOpen(true)}
+        onKeyDown={handleKeyDown}
+        shortcut="⌘K"
+        size="sm"
+      />
+      {isOpen && results.length > 0 && (
+        <Listbox aria-label="Search results" className="shared-docs-search-results">
+          {results.map((item, index) => (
+            <Listbox.Item
+              key={`${item.section}:${item.href}`}
+              selected={index === selectedIndex}
+              onClick={() => handleSelect(item)}
+              onMouseEnter={() => setSelectedIndex(index)}
+            >
+              <span className="shared-docs-search-result-label">{item.label}</span>
+              <span className="shared-docs-search-result-section">{item.section}</span>
+            </Listbox.Item>
+          ))}
+        </Listbox>
+      )}
+      {isOpen && query.trim() && results.length === 0 && (
+        <Listbox aria-label="Search results" className="shared-docs-search-results">
+          <Listbox.Empty>No results found</Listbox.Empty>
+        </Listbox>
+      )}
+    </div>
+  );
+}

package/src/viewer/vendor/shared/src/DocsSidebarNav.tsx

@@ -0,0 +1,66 @@
+'use client';
+
+import { Sidebar } from '@fragments-sdk/ui';
+import type { ReactNode } from 'react';
+import type { DocsNavLinkRenderer, NavSection } from './types';
+
+interface DocsSidebarNavProps {
+  sections: NavSection[];
+  currentPath: string;
+  renderLink?: DocsNavLinkRenderer;
+  onNavigate?: () => void;
+  isActive?: (href: string, currentPath: string) => boolean;
+  footer?: ReactNode;
+  ariaLabel?: string;
+}
+
+function defaultIsActive(href: string, currentPath: string): boolean {
+  return currentPath === href;
+}
+
+const defaultLinkRenderer: DocsNavLinkRenderer = ({ href, label, onClick }) => (
+  <a href={href} onClick={onClick}>
+    {label}
+  </a>
+);
+
+export function DocsSidebarNav({
+  sections,
+  currentPath,
+  renderLink = defaultLinkRenderer,
+  onNavigate,
+  isActive = defaultIsActive,
+  footer,
+  ariaLabel = 'Navigation',
+}: DocsSidebarNavProps) {
+  return (
+    <>
+      <Sidebar.Nav aria-label={ariaLabel}>
+        {sections.map((section) => (
+          <Sidebar.Section
+            key={section.title}
+            label={section.title}
+            collapsible={section.collapsible}
+            defaultOpen={section.defaultOpen}
+          >
+            {section.items.map((item) => (
+              <Sidebar.Item
+                key={item.href}
+                active={isActive(item.href, currentPath)}
+                asChild
+              >
+                {renderLink({
+                  href: item.href,
+                  label: item.label,
+                  onClick: onNavigate,
+                })}
+              </Sidebar.Item>
+            ))}
+          </Sidebar.Section>
+        ))}
+      </Sidebar.Nav>
+
+      <Sidebar.Footer>{footer}</Sidebar.Footer>
+    </>
+  );
+}

package/src/viewer/vendor/shared/src/docs-layout.scss

@@ -0,0 +1,28 @@
+.shared-docs-main-content {
+  width: 100%;
+}
+
+.shared-docs-search-container {
+  position: relative;
+  width: 100%;
+  max-width: 240px;
+}
+
+.shared-docs-search-results {
+  position: absolute;
+  top: calc(100% + 4px);
+  left: 0;
+  right: 0;
+  z-index: 100;
+}
+
+.shared-docs-search-result-label {
+  flex: 1;
+  font-weight: var(--fui-font-weight-medium);
+}
+
+.shared-docs-search-result-section {
+  font-size: var(--fui-font-size-xs);
+  color: var(--fui-text-tertiary);
+  margin-left: auto;
+}

package/src/viewer/vendor/shared/src/docs-layout.scss.d.ts

@@ -0,0 +1,2 @@
+declare const styles: string;
+export default styles;

package/src/viewer/vendor/shared/src/index.ts

@@ -0,0 +1,26 @@
+'use client';
+
+import './docs-layout.scss';
+
+export { DocsPageShell } from './DocsPageShell';
+export { DocsSidebarNav } from './DocsSidebarNav';
+export { DocsSearchCommand } from './DocsSearchCommand';
+export { DocsHeaderBar } from './DocsHeaderBar';
+export {
+  DocsPageAsideHost,
+  DocsPageAsidePortal,
+  DocsPageAsideProvider,
+  useDocsPageAside,
+} from './DocsPageAsideHost';
+
+export type {
+  NavItem,
+  NavSection,
+  SearchItem,
+  DocsNavLinkRenderProps,
+  DocsNavLinkRenderer,
+  HeaderNavEntry,
+  HeaderNavLink,
+  HeaderNavDropdown,
+} from './types';
+export { isDropdown } from './types';

package/src/viewer/vendor/shared/src/types.ts

@@ -0,0 +1,41 @@
+import type { ReactElement } from 'react';
+
+export interface NavItem {
+  label: string;
+  href: string;
+}
+
+export interface NavSection {
+  title: string;
+  items: NavItem[];
+  collapsible?: boolean;
+  defaultOpen?: boolean;
+}
+
+export interface SearchItem extends NavItem {
+  section: string;
+}
+
+export interface DocsNavLinkRenderProps {
+  href: string;
+  label: string;
+  onClick?: () => void;
+}
+
+export type DocsNavLinkRenderer = (props: DocsNavLinkRenderProps) => ReactElement;
+
+export interface HeaderNavLink {
+  label: string;
+  href: string;
+}
+
+export interface HeaderNavDropdown {
+  label: string;
+  items: NavItem[];
+}
+
+export type HeaderNavEntry = HeaderNavLink | HeaderNavDropdown;
+
+export function isDropdown(entry: HeaderNavEntry): entry is HeaderNavDropdown {
+  return 'items' in entry;
+}