@terrafirmagreg-team/kit 0.0.0-stage → 0.1.0

package/src/components/page-actions.tsx

@@ -0,0 +1,201 @@
+'use client';
+import { type ComponentProps } from 'react';
+import {
+  Check,
+  ChevronDown,
+  Copy,
+  ExternalLinkIcon,
+  Languages,
+  TextIcon,
+} from 'lucide-react';
+import { SiGithub } from '@icons-pack/react-simple-icons';
+import { cn } from '@terrafirmagreg-team/ui/lib/utils/cn';
+import { Button } from '@terrafirmagreg-team/ui/components/ui/button';
+import {
+  Popover,
+  PopoverTrigger,
+  PopoverContent,
+} from '@terrafirmagreg-team/ui/components/ui/popover';
+import { ItemRow } from '@terrafirmagreg-team/ui/components/blocks/list/row';
+import { useUntranslated } from '@terrafirmagreg-team/ui/hooks/lang';
+import { useTranslations } from '@terrafirmagreg-team/translate/hooks/use-translations';
+import { useCopyButton } from '@terrafirmagreg-team/ui/hooks/use-copy-button';
+import {
+  openPageMarkdown,
+  pageMarkdown,
+} from '@terrafirmagreg-team/kit/lib/markdown';
+import type { TranslationState } from '@terrafirmagreg-team/translate/server';
+
+function ActionButton({
+  className,
+  ...props
+}: ComponentProps<typeof Button>) {
+  return (
+    <Button
+      variant="secondary"
+      size="sm"
+      className={cn(
+        'gap-2 border-foreground/10 hover:bg-background dark:hover:bg-accent [&_svg]:size-3.5 [&_svg]:text-muted-foreground',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export function MarkdownCopyButton({
+  getMarkdown,
+  ...props
+}: ComponentProps<'button'> & {
+  getMarkdown: () => Promise<string>;
+}) {
+  const t = useTranslations();
+  const { isLoading, checked, error, onClick } = useCopyButton(getMarkdown);
+
+  return (
+    <ActionButton
+      disabled={isLoading}
+      aria-live="polite"
+      onClick={onClick}
+      {...props}
+    >
+      {checked ? <Check /> : <Copy />}
+      {props.children ??
+        (error
+          ? t('ui.copy_error')
+          : checked
+            ? t('ui.copied_markdown')
+            : t('ui.copy_markdown'))}
+    </ActionButton>
+  );
+}
+
+export function CopyPageMarkdown({ title }: { title: string }) {
+  return (
+    <MarkdownCopyButton
+      getMarkdown={() =>
+        pageMarkdown(document.querySelector('[data-md-root]'), title)
+      }
+    />
+  );
+}
+
+export function CrowdinButton({ url }: { url: string }) {
+  const t = useTranslations();
+  return (
+    <ActionButton
+      nativeButton={false}
+      render={<a href={url} target="_blank" rel="noreferrer" />}
+    >
+      <Languages />
+      {t('untranslated.translate')}
+    </ActionButton>
+  );
+}
+
+export function UntranslatedActions({
+  copied,
+  crowdinUrl,
+}: {
+  copied?: TranslationState;
+  crowdinUrl?: string;
+}) {
+  const missing = useUntranslated();
+  if (!crowdinUrl || (!missing && !copied)) return null;
+  return <CrowdinButton url={crowdinUrl} />;
+}
+
+export function ViewOptionsPopover({
+  githubUrl,
+  title,
+  mdUrl,
+  ...props
+}: ComponentProps<typeof PopoverTrigger> & {
+  githubUrl?: string;
+  title?: string;
+  mdUrl?: string;
+}) {
+  const t = useTranslations();
+  const items = [
+    githubUrl && {
+      title: t('ui.open_github'),
+      href: githubUrl,
+      icon: <SiGithub color="currentColor" className="size-4" />,
+    },
+    (mdUrl || title !== undefined) && {
+      title: t('ui.view_markdown'),
+      ...(mdUrl
+        ? { href: mdUrl }
+        : {
+            onClick: () =>
+              void openPageMarkdown(
+                document.querySelector('[data-md-root]'),
+                title!,
+              ),
+          }),
+      icon: <TextIcon className="size-4" />,
+    },
+  ].filter((v) => !!v);
+  if (!items.length) return null;
+
+  return (
+    <Popover>
+      <PopoverTrigger
+        {...props}
+        render={
+          <Button
+            variant="secondary"
+            size="sm"
+            className="border-foreground/10 hover:bg-background dark:hover:bg-accent"
+          />
+        }
+        className={(state) =>
+          cn(
+            'gap-2 data-[popup-open]:bg-accent data-[popup-open]:text-accent-foreground',
+            typeof props.className === 'function' ? props.className(state) : props.className,
+          )
+        }
+      >
+        {props.children ?? t('ui.open')}
+        <ChevronDown className="size-3.5 text-muted-foreground" />
+      </PopoverTrigger>
+      <PopoverContent className="flex flex-col">
+        {items.map((item) => (
+          <ItemRow
+            key={item.title}
+            {...('href' in item
+              ? { href: item.href, target: '_blank', rel: 'noreferrer noopener' }
+              : { onClick: item.onClick })}
+            media={item.icon}
+            title={item.title}
+            trailing={
+              <ExternalLinkIcon className="size-3.5 text-muted-foreground" />
+            }
+          />
+        ))}
+      </PopoverContent>
+    </Popover>
+  );
+}
+
+export function PageActions({
+  copied,
+  crowdinUrl,
+  title,
+  mdUrl,
+  githubUrl,
+}: {
+  copied?: TranslationState;
+  crowdinUrl?: string;
+  title: string;
+  mdUrl?: string;
+  githubUrl?: string;
+}) {
+  return (
+    <>
+      <CopyPageMarkdown title={title} />
+      <ViewOptionsPopover title={title} mdUrl={mdUrl} githubUrl={githubUrl} />
+      <UntranslatedActions copied={copied} crowdinUrl={crowdinUrl} />
+    </>
+  );
+}

package/src/components/relative-link.tsx

@@ -0,0 +1,18 @@
+import type { LoaderConfig, LoaderOutput, Page } from 'fumadocs-core/source';
+import type { ComponentProps, ReactNode } from 'react';
+import Link from 'fumadocs-core/link';
+
+export function createRelativeLink<C extends LoaderConfig>(
+  source: LoaderOutput<C>,
+  page: Page | C['page'],
+  OverrideLink: (props: ComponentProps<'a'>) => ReactNode = Link,
+): (props: ComponentProps<'a'>) => ReactNode | Promise<ReactNode> {
+  return async function RelativeLink({ href, ...props }) {
+    return (
+      <OverrideLink
+        href={href ? source.resolveHref(href, page) : href}
+        {...props}
+      />
+    );
+  };
+}

package/src/components/search/dialog.tsx

@@ -0,0 +1,145 @@
+'use client';
+import {
+  SearchDialog as SearchDialogRoot,
+  SearchDialogClose,
+  SearchDialogContent,
+  SearchDialogFooter,
+  SearchDialogHeader,
+  SearchDialogIcon,
+  SearchDialogInput,
+  SearchDialogList,
+  SearchDialogOverlay,
+  SearchTagsList,
+  SearchTagsListItem,
+  type SharedProps,
+} from '@terrafirmagreg-team/ui/components/blocks/search/dialog';
+import {
+  useDocsSearch,
+  type SearchClient,
+} from 'fumadocs-core/search/client';
+import { staticClient } from 'fumadocs-core/search/client/orama-static';
+import { useResolvedLang } from '@terrafirmagreg-team/translate/hooks/use-resolved-lang';
+import { usePathname } from 'next/navigation';
+import { useMemo, useState } from 'react';
+import { Skeleton } from '@terrafirmagreg-team/ui/components/ui/skeleton';
+import { useTranslations } from '@terrafirmagreg-team/translate/hooks/use-translations';
+import { useSectionCatalog } from '@terrafirmagreg-team/kit/hooks/use-catalog';
+import {
+  dumpSectionKeys,
+  isDumpSection,
+  parseDatasetRef,
+  parseSectionLocation,
+} from '@terrafirmagreg-team/kit/lib/location';
+import { searchHitFilter, mergeClients } from '@terrafirmagreg-team/kit/lib/search';
+import { getSearchClientSources } from '@terrafirmagreg-team/kit/lib/search/sources';
+
+type Scope = 'dataset' | 'section' | 'all';
+
+export function SearchDialog(props: SharedProps & { api: string }) {
+  const locale = useResolvedLang();
+  const t = useTranslations();
+  const catalog = useSectionCatalog();
+  const pathname = usePathname();
+  const { section, dataset: locationDataset } =
+    parseSectionLocation(pathname);
+  const dataset = locationDataset
+    ? parseDatasetRef(locationDataset).id
+    : undefined;
+  const scopeKey = `${section ?? ''}/${locationDataset ?? ''}`;
+  const defaultScope: Scope = dataset
+    ? 'dataset'
+    : section
+      ? 'section'
+      : 'all';
+  const [picked, setPicked] = useState<{ key: string; value: Scope }>();
+  const scope = picked?.key === scopeKey ? picked.value : defaultScope;
+  const setScope = (value: Scope) => setPicked({ key: scopeKey, value });
+
+  const tag = useMemo((): string | string[] | undefined => {
+    if (!section || scope === 'all') return undefined;
+    if (scope === 'dataset' && dataset) {
+      return `${section}:${dataset}`;
+    }
+    const ids = catalog[section].map(({ id }) => `${section}:${id}`);
+    return ids.length > 0 ? ids : `${section}:`;
+  }, [scope, section, dataset, catalog]);
+
+  const client = useMemo((): SearchClient => {
+    const content = staticClient({ locale, tag, from: props.api });
+
+    const scopedSections =
+      scope === 'all'
+        ? dumpSectionKeys()
+        : section && isDumpSection(section)
+          ? [section]
+          : [];
+    const refs = scopedSections.flatMap((sec) =>
+      (catalog[sec] ?? []).map(({ id }) =>
+        sec === section && id === dataset && locationDataset
+          ? locationDataset
+          : id,
+      ),
+    );
+    const extra = getSearchClientSources().map((make) =>
+      make({ refs, locale, tag }),
+    );
+    return mergeClients(content, ...extra);
+  }, [locale, tag, section, scope, dataset, locationDataset, catalog, props.api]);
+  const { search, setSearch, query } = useDocsSearch({ client });
+  const items = useMemo(() => {
+    const list = query.data !== 'empty' ? (query.data ?? []) : [];
+    const hitFilter =
+      section && typeof window !== 'undefined'
+        ? searchHitFilter(
+            section,
+            new URLSearchParams(window.location.search),
+          )
+        : undefined;
+    return hitFilter ? list.filter(hitFilter) : list;
+  }, [query.data, section]);
+  const datasetMeta = catalog[section ?? 'docs']?.find(
+    ({ id }) => id === dataset,
+  );
+
+  return (
+    <SearchDialogRoot search={search} onSearchChange={setSearch} isLoading={query.isLoading} {...props}>
+      <SearchDialogOverlay />
+      <SearchDialogContent>
+        <SearchDialogHeader>
+          <SearchDialogIcon />
+          <SearchDialogInput />
+          <SearchDialogClose />
+        </SearchDialogHeader>
+        {query.isLoading ? (
+          <div className="flex flex-col gap-1.5 p-3">
+            <Skeleton className="h-9 w-full" />
+            <Skeleton className="h-9 w-5/6" />
+            <Skeleton className="h-9 w-4/6" />
+          </div>
+        ) : (
+          <SearchDialogList items={items.length ? items : null} />
+        )}
+        {section && (
+          <SearchDialogFooter>
+            <SearchTagsList
+              tag={scope}
+              onTagChange={(value) => setScope((value as Scope) ?? 'all')}
+            >
+              {dataset && (
+                <SearchTagsListItem value="dataset">
+                  {datasetMeta?.title ?? dataset}
+                </SearchTagsListItem>
+              )}
+              <SearchTagsListItem value="section">
+                {t(`sections.${section}`)}
+              </SearchTagsListItem>
+              <SearchTagsListItem value="all">
+                {t('ui.search_everywhere')}
+              </SearchTagsListItem>
+            </SearchTagsList>
+          </SearchDialogFooter>
+        )}
+      </SearchDialogContent>
+    </SearchDialogRoot>
+  );
+}

package/src/components/toc/base.tsx

@@ -0,0 +1,65 @@
+'use client';
+import {
+  AnchorProvider,
+  ScrollProvider,
+  type AnchorProviderProps,
+} from 'fumadocs-core/toc';
+import { useRef, type ComponentProps } from 'react';
+import { TOCContext } from '@terrafirmagreg-team/kit/hooks/toc';
+import { cn } from '@terrafirmagreg-team/ui/lib/utils/cn';
+import { mergeRefs } from '@terrafirmagreg-team/ui/lib/utils/merge-refs';
+
+export {
+  AnchorProvider,
+  ScrollProvider,
+  TOCItem,
+  useActiveAnchor,
+  useActiveAnchors,
+  useItems,
+  useTOC,
+  useTOCListener,
+  useTOCSelector,
+} from 'fumadocs-core/toc';
+export type {
+  AnchorProviderProps,
+  ScrollProviderProps,
+  TOCItemInfo,
+  TOCItemProps,
+  TOCItemType,
+  TableOfContents,
+} from 'fumadocs-core/toc';
+
+export type TOCProviderProps = AnchorProviderProps;
+
+export function TOCProvider({ toc, children, ...props }: TOCProviderProps) {
+  return (
+    <TOCContext value={toc}>
+      <AnchorProvider toc={toc} {...props}>
+        {children}
+      </AnchorProvider>
+    </TOCContext>
+  );
+}
+
+export function TOCScrollArea({
+  ref,
+  className,
+  ...props
+}: ComponentProps<'div'>) {
+  const viewRef = useRef<HTMLDivElement>(null);
+
+  return (
+    <div
+      ref={mergeRefs(viewRef, ref)}
+      className={cn(
+        'relative min-h-0 text-sm overflow-x-clip overflow-y-auto overscroll-contain [scrollbar-width:none] mask-[linear-gradient(to_bottom,transparent,white_16px,white_calc(100%-16px),transparent)] py-3',
+        className,
+      )}
+      {...props}
+    >
+      <ScrollProvider containerRef={viewRef}>
+        {props.children}
+      </ScrollProvider>
+    </div>
+  );
+}

package/src/components/toc/block.tsx

@@ -0,0 +1,111 @@
+'use client';
+import { useEffect, useRef, type ComponentProps } from 'react';
+import { cn } from '@terrafirmagreg-team/ui/lib/utils/cn';
+import { mergeRefs } from '@terrafirmagreg-team/ui/lib/utils/merge-refs';
+import * as Primitive from './base';
+import { TOCEmpty } from './default';
+
+export { TOCEmpty };
+
+export type TOCItemsProps = ComponentProps<'div'>;
+
+export function TOCItems({
+  ref,
+  className,
+  children,
+  ...props
+}: TOCItemsProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const blockRef = useRef<HTMLDivElement>(null);
+  const tocInfo = Primitive.useTOC();
+
+  useEffect(() => {
+    const container = containerRef.current;
+    const block = blockRef.current;
+    if (!container || !block) return;
+
+    const positions = new Map<string, [number, number]>();
+    let height = 0;
+
+    const update = (items: Primitive.TOCItemInfo[]) => {
+      let top = -1;
+      let bottom = -1;
+      for (const item of items) {
+        if (!item.active) continue;
+        const pos = positions.get(item.original.url);
+        if (!pos) continue;
+        if (top === -1) top = pos[0];
+        bottom = pos[1];
+      }
+      if (top === -1) return;
+      block.style.clipPath = `inset(${top}px 0 ${height - bottom}px round 8px)`;
+      if (!block.hasAttribute('data-ready'))
+        requestAnimationFrame(() => block.setAttribute('data-ready', ''));
+    };
+
+    const observer = new ResizeObserver(() => {
+      positions.clear();
+      for (const anchor of container.getElementsByTagName('a')) {
+        const href = anchor.getAttribute('href');
+        if (href)
+          positions.set(href, [
+            anchor.offsetTop,
+            anchor.offsetTop + anchor.offsetHeight,
+          ]);
+      }
+      height = container.clientHeight;
+      update(tocInfo.get());
+    });
+
+    observer.observe(container);
+    tocInfo.listen(update);
+    return () => {
+      observer.disconnect();
+      tocInfo.unlisten(update);
+    };
+  }, [tocInfo]);
+
+  return (
+    <div
+      ref={mergeRefs(containerRef, ref)}
+      className={cn('relative flex flex-col', className)}
+      {...props}
+    >
+      <div
+        ref={blockRef}
+        className="absolute inset-0 bg-linear-to-r from-primary/10 [clip-path:inset(0_0_100%)] data-ready:transition-[clip-path] duration-300 ease-out"
+      />
+      {children}
+    </div>
+  );
+}
+
+function getItemOffset(depth: number): number {
+  if (depth <= 2) return 8;
+  if (depth === 3) return 20;
+  return 32;
+}
+
+export function TOCItem({
+  item,
+  ...props
+}: Primitive.TOCItemProps & { item: Primitive.TOCItemType }) {
+  return (
+    <Primitive.TOCItem
+      href={item.url}
+      {...props}
+      className={cn(
+        'group prose relative py-1 pe-2 text-[0.8125rem]/5 scroll-m-4 text-muted-foreground hover:text-accent-foreground transition-colors wrap-anywhere data-[active=true]:text-primary',
+        props.className,
+      )}
+      style={{ paddingInlineStart: getItemOffset(item.depth), ...props.style }}
+    >
+      {item._step !== undefined && (
+        <span className="inline-flex size-4 me-1.5 items-center justify-center rounded-full align-text-bottom bg-muted text-muted-foreground font-mono font-medium text-[10px] transition-colors group-data-[active=true]:bg-primary group-data-[active=true]:text-primary-foreground">
+          {item._step}
+        </span>
+      )}
+      {item.title}
+    </Primitive.TOCItem>
+  );
+}