@terrafirmagreg-team/game 0.0.0-stage → 1.2.0

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@terrafirmagreg-team/game",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.2.0",
+  "type": "module",
+  "description": "Game-data components and catalogs",
+  "license": "LGPL-3.0-only",
+  "exports": {
+    "./components/*": [
+      "./src/components/*.tsx",
+      "./src/components/*/index.tsx",
+      "./src/components/*/index.ts"
+    ],
+    "./hooks/*": [
+      "./src/hooks/*.ts",
+      "./src/hooks/*/index.ts"
+    ],
+    "./lib/*": [
+      "./src/lib/*.ts",
+      "./src/lib/*/index.ts"
+    ],
+    "./types/*": [
+      "./src/types/*.ts",
+      "./src/types/*/index.ts"
+    ],
+    "./styles.css": "./styles.css",
+    "./locales": "./src/locales.ts"
+  },
+  "dependencies": {
+    "@terrafirmagreg-team/data": "1.2.0",
+    "@terrafirmagreg-team/dump": "1.2.0",
+    "@terrafirmagreg-team/kit": "1.2.0",
+    "@terrafirmagreg-team/search": "1.2.0",
+    "@terrafirmagreg-team/sites": "1.2.0",
+    "@terrafirmagreg-team/translate": "1.2.0",
+    "@terrafirmagreg-team/ui": "1.2.0",
+    "fumadocs-core": "16.17.8",
+    "lucide-react": "^0.577.0",
+    "server-only": "^0.0.1"
+  },
+  "peerDependencies": {
+    "next": ">=15",
+    "react": ">=19"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TerraFirmaGreg-Team/Web-Foundation.git",
+    "directory": "packages/game"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "styles",
+    "styles.css"
+  ]
 }

package/src/components/entry/atlas-sprite.tsx

@@ -0,0 +1,44 @@
+'use client';
+import type { DatasetRef } from '@terrafirmagreg-team/sites/location';
+
+import { atlasPagePublicUrl } from '@terrafirmagreg-team/dump/lib/dump/assets/atlas/lookup';
+import type { AtlasLookup } from '@terrafirmagreg-team/dump/lib/dump/assets/atlas/dto';
+import { Sprite } from '@terrafirmagreg-team/ui/components/blocks/sprite';
+import { Skeleton } from '@terrafirmagreg-team/ui/components/ui/skeleton';
+import { cn } from '@terrafirmagreg-team/ui/lib/utils/cn';
+
+export function AtlasSprite({
+  dataset,
+  lookup,
+  size = 16,
+  className,
+}: {
+  dataset: DatasetRef;
+  lookup: AtlasLookup | null;
+  size?: number;
+  className?: string;
+}) {
+  const url = lookup
+    ? atlasPagePublicUrl(dataset, lookup.atlas, lookup.page)
+    : undefined;
+  return (
+    <Sprite
+      src={url}
+      rect={lookup ? lookup.sprite : undefined}
+      page={lookup ? lookup.page : undefined}
+      tint={
+        lookup?.sprite.tintColor && lookup.sprite.tint !== 'none'
+          ? lookup.sprite.tintColor
+          : undefined
+      }
+      size={size}
+      className={className}
+      fallback={
+        <Skeleton
+          className={cn('inline-block shrink-0', className)}
+          style={{ width: size, height: size }}
+        />
+      }
+    />
+  );
+}

package/src/components/entry/copy-id-menu.tsx

@@ -0,0 +1,48 @@
+'use client';
+
+import { Copy } from 'lucide-react';
+import type { ReactNode } from 'react';
+import { CopyMenu } from '@terrafirmagreg-team/ui/components/blocks/nav/copy-menu';
+import { useTranslations } from '@terrafirmagreg-team/translate/hooks/use-translations';
+
+export function CopyIdMenu({
+  id,
+  nbt,
+  label,
+  extra,
+  children,
+}: {
+  id: string;
+
+  nbt?: string;
+
+  label?: string;
+
+  extra?: ReactNode;
+  children: ReactNode;
+}) {
+  const t = useTranslations();
+  return (
+    <CopyMenu
+      items={[
+        {
+          icon: <Copy />,
+          label: label ?? t('Copy id', { note: 'ui.entry.copy' }),
+          value: id,
+        },
+        ...(nbt
+          ? [
+              {
+                label: t('Copy stack id', { note: 'ui.entry.copy_stack' }),
+                value: `${id}${nbt}`,
+              },
+              { label: t('Copy NBT', { note: 'ui.entry.copy_nbt' }), value: nbt },
+            ]
+          : []),
+      ]}
+      extra={extra}
+    >
+      {children}
+    </CopyMenu>
+  );
+}

package/src/components/entry/entry.tsx

@@ -0,0 +1,308 @@
+'use client';
+
+import Link from 'next/link';
+import { usePathname } from 'next/navigation';
+import { parseSectionLocation } from '@terrafirmagreg-team/sites/location';
+import type { ReactElement } from 'react';
+import { EntryIcon } from '@terrafirmagreg-team/game/components/entry/icon';
+import { EntryTooltip } from '@terrafirmagreg-team/game/components/entry/tooltip';
+import { CopyIdMenu } from '@terrafirmagreg-team/game/components/entry/copy-id-menu';
+import { useEntryContext } from '@terrafirmagreg-team/game/hooks/use-entry-context';
+import { useLangMap } from '@terrafirmagreg-team/game/hooks/use-lang-map';
+import { ResolvedLangContext } from '@terrafirmagreg-team/translate/hooks/use-resolved-lang';
+import { useContext, useMemo } from 'react';
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from '@terrafirmagreg-team/ui/components/ui/tooltip';
+import {
+  classifyRefId,
+  isIconKind,
+  isTagKind,
+  refId,
+} from '@terrafirmagreg-team/dump/lib/dump/contract/ref';
+import { formatNbt } from '@terrafirmagreg-team/dump/lib/snbt';
+import { fetchEntityModel } from '@terrafirmagreg-team/game/lib/entry/icon-load';
+import { useDumpLocation } from '@terrafirmagreg-team/game/hooks/use-dump-location';
+import { createDumpAssetResolver } from '@terrafirmagreg-team/dump/lib/dump/assets/urls';
+import { GlbViewer } from '@terrafirmagreg-team/ui/components/blocks/media/glb/viewer';
+import { stackIdFromRef } from '@terrafirmagreg-team/dump/lib/dump/contract/ref';
+import { stackDisplay } from '@terrafirmagreg-team/game/lib/entry/display';
+import { loadStackDisplay } from '@terrafirmagreg-team/game/lib/entry/tooltip';
+import { useAsyncResult } from '@terrafirmagreg-team/ui/hooks/use-async-value';
+import {
+  resolveEntryHref,
+  tooltipLoadKind,
+  usesStackTooltip,
+} from '@terrafirmagreg-team/game/lib/entry/entry';
+import { cn } from '@terrafirmagreg-team/ui/lib/utils/cn';
+import type {
+  BlockDirectiveProps,
+  EntityDirectiveProps,
+  EntryProps,
+  FluidDirectiveProps,
+  ItemDirectiveProps,
+  KindEntryProps,
+  RecipeDirectiveProps,
+  TagDirectiveProps,
+} from '@terrafirmagreg-team/game/types/entry';
+
+export function Entry({
+  reference: referenceProp,
+  id,
+  kind,
+  tag,
+  copy,
+  dataset: datasetProp,
+  name: nameProp,
+  lang: langProp,
+  langMap: langMapProp,
+  size = 'md',
+  variant = 'plain',
+  badge,
+  badgeClassName,
+  labeled = false,
+  label,
+  className,
+  missing,
+  tooltip,
+  children,
+  entityView,
+  icon: iconProp,
+  ...hrefOpts
+}: EntryProps) {
+  const ctx = useEntryContext();
+  const pathname = usePathname();
+  const locId = parseSectionLocation(pathname).dataset;
+  const dataset =
+    datasetProp ?? ctx?.dataset ?? (locId ? { id: locId } : undefined);
+  const resolvedLang = useContext(ResolvedLangContext)?.lang;
+  const lang = langProp ?? ctx?.lang ?? resolvedLang;
+  const fetchedLangMap = useLangMap(
+    dataset,
+    lang,
+    langMapProp === undefined && !ctx?.langMap,
+  );
+  const langMap = langMapProp ?? ctx?.langMap ?? fetchedLangMap;
+  const classified = id ? classifyRefId(id, kind) : undefined;
+  const reference =
+    referenceProp ??
+    (classified && tag !== undefined ? { ...classified, tag } : classified);
+  const refKind = reference?.kind;
+  const refIdStr = reference?.id ?? id ?? '';
+  const iconKind = refKind && isIconKind(refKind) ? refKind : undefined;
+  const stackId = reference ? stackIdFromRef(reference) : refIdStr;
+  const displayKey =
+    dataset &&
+    stackId &&
+    (refKind === 'item' ||
+      refKind === 'block' ||
+      refKind === 'fluid' ||
+      refKind === 'entity')
+      ? `${dataset.id}/${dataset.version ?? ''}:${stackId}`
+      : undefined;
+  const displayPeek =
+    displayKey && dataset
+      ? loadStackDisplay.peek(
+          dataset,
+          stackId,
+          refKind === 'fluid'
+            ? 'fluid'
+            : refKind === 'entity'
+              ? 'entity'
+              : 'item',
+        )
+      : undefined;
+  const stackDisplayRes = useAsyncResult(
+    displayKey && dataset && displayPeek === undefined
+      ? async () => ({
+          key: displayKey,
+          display: await loadStackDisplay(
+            dataset,
+            stackId,
+            refKind === 'fluid'
+              ? 'fluid'
+              : refKind === 'entity'
+                ? 'entity'
+                : 'item',
+          ),
+        })
+      : false,
+    [dataset, stackId, displayKey, refKind, displayPeek],
+  );
+  const stackMissing =
+    displayKey !== undefined &&
+    displayPeek === undefined &&
+    !stackDisplayRes.pending &&
+    stackDisplayRes.value?.key === displayKey &&
+    stackDisplayRes.value.display === undefined;
+  const langKey =
+    displayPeek !== undefined
+      ? displayPeek?.name
+      : stackDisplayRes.value && stackDisplayRes.value.key === displayKey
+        ? stackDisplayRes.value.display?.name
+        : undefined;
+  const display = stackDisplay(langMap, stackId, refKind, langKey);
+  const name = nameProp ?? display.name;
+  const preferVariant =
+    reference?.tag === undefined &&
+    (refKind === 'item' || refKind === 'block' || refKind === 'fluid') &&
+    langMap !== undefined &&
+    !display.localized;
+  const resolved =
+    dataset && !stackMissing
+      ? resolveEntryHref({
+          reference,
+          id: refIdStr,
+          kind: refKind,
+          tag,
+          dataset,
+          name,
+          lang,
+          ...hrefOpts,
+        })
+      : undefined;
+  const faceClass = cn('inline-flex items-center justify-center', className);
+
+  const icon = (
+    <EntryIcon
+      reference={iconProp ?? reference}
+      id={iconProp ? refId(iconProp) : refIdStr}
+      kind={
+        iconProp
+          ? isIconKind(iconProp.kind)
+            ? iconProp.kind
+            : undefined
+          : iconKind
+      }
+      tag={tag}
+      dataset={dataset}
+      size={size}
+      labeled={labeled}
+      label={label ?? (labeled ? name : undefined)}
+      missing={missing}
+      chip={variant === 'chip'}
+      preferVariant={preferVariant}
+      entityView={entityView}
+      badge={badge}
+      badgeClassName={badgeClassName}
+    >
+      {children}
+    </EntryIcon>
+  );
+
+  let face: ReactElement = resolved ? (
+    <Link
+      href={resolved}
+      className={faceClass}
+      aria-label={name}
+    >
+      {icon}
+    </Link>
+  ) : (
+    <span className={faceClass}>{icon}</span>
+  );
+
+  const copyNbt = reference?.tag !== undefined ? formatNbt(reference.tag) : undefined;
+  const copyId =
+    reference && isTagKind(reference.kind)
+      ? `#${reference.id.replace(/^#+/, '')}`
+      : refIdStr;
+  if (copy && refIdStr) {
+    face = (
+      <CopyIdMenu id={copyId} nbt={copyNbt}>
+        {face}
+      </CopyIdMenu>
+    );
+  }
+
+  if (tooltip === false) return face;
+  const tooltipLevel = typeof tooltip === 'string' ? tooltip : undefined;
+  if (dataset && (tooltip || usesStackTooltip(refKind))) {
+    return (
+      <EntryTooltip
+        dataset={dataset}
+        id={reference ? refId(reference) : (id ?? '')}
+        name={name}
+        kind={tooltipLoadKind(refKind)}
+        lang={lang}
+        langMap={langMap}
+        level={tooltipLevel}
+      >
+        {face}
+      </EntryTooltip>
+    );
+  }
+  return (
+    <Tooltip>
+      <TooltipTrigger render={face} />
+      <TooltipContent>{name}</TooltipContent>
+    </Tooltip>
+  );
+}
+
+function kindEntry<P extends KindEntryProps>(kind: EntryProps['kind']) {
+  function KindEntry(props: P) {
+    return <Entry kind={kind} {...props} />;
+  }
+  return KindEntry;
+}
+
+export const ItemEntry = kindEntry<ItemDirectiveProps>('item');
+export const BlockEntry = kindEntry<BlockDirectiveProps>('block');
+export const FluidEntry = kindEntry<FluidDirectiveProps>('fluid');
+export function EntityEntry({
+  view = 'auto',
+  id,
+  dataset: datasetProp,
+  name,
+  ...rest
+}: EntityDirectiveProps) {
+  const ctx = useEntryContext();
+  const pathname = usePathname();
+  const locId = parseSectionLocation(pathname).dataset;
+  const dataset = useMemo(
+    () =>
+      datasetProp ?? ctx?.dataset ?? (locId ? { id: locId } : undefined),
+    [datasetProp, ctx, locId],
+  );
+  const modelKey = dataset && id ? `${dataset.id}/${dataset.version ?? ''}:${id}` : undefined;
+  const modelRes = useAsyncResult(
+    view === 'model' && modelKey
+      ? async () => ({
+          key: modelKey,
+          url: await fetchEntityModel(dataset!, id!),
+        })
+      : false,
+    [view, dataset, id, modelKey],
+  );
+  useDumpLocation(dataset);
+  const resolveResource = useMemo(
+    () => (dataset ? createDumpAssetResolver(dataset) : undefined),
+    [dataset],
+  );
+  if (view === 'model') {
+    const model = modelRes.value;
+    const src = model && model.key === modelKey ? model.url : undefined;
+    if (src === undefined) return null;
+    return src ? (
+      <GlbViewer src={src} title={name ?? id} resolveResource={resolveResource} />
+    ) : (
+      <Entry kind="entity" id={id} dataset={dataset} name={name} {...rest} />
+    );
+  }
+  return (
+    <Entry
+      kind="entity"
+      id={id}
+      dataset={dataset}
+      name={name}
+      entityView={view}
+      {...rest}
+    />
+  );
+}
+export const TagEntry = kindEntry<TagDirectiveProps>('itemTag');
+export const RecipeEntry = kindEntry<RecipeDirectiveProps>('recipe');
+

package/src/components/entry/group.tsx

@@ -0,0 +1,161 @@
+'use client';
+import type { DatasetRef } from '@terrafirmagreg-team/sites/location';
+
+import {
+  SPRITE_CLUSTER_INSET,
+  SPRITE_CLUSTER_UNITS,
+  SpriteCluster,
+} from '@terrafirmagreg-team/ui/components/blocks/sprite';
+import { EntryIcon, entrySizePx, ENTRY_CYCLE_MS } from '@terrafirmagreg-team/game/components/entry/icon';
+import { useCycleIndex } from '@terrafirmagreg-team/ui/hooks/use-cycle-index';
+import { useAsyncResult } from '@terrafirmagreg-team/ui/hooks/use-async-value';
+import { fetchTagMembers } from '@terrafirmagreg-team/game/lib/entry/icon-load';
+import {
+  classifyRefId,
+  isTagKind,
+  stackIdFromRef,
+  tagKindOf,
+  type ReferenceKind,
+  type TaggedReference,
+} from '@terrafirmagreg-team/dump/lib/dump/contract/ref';
+import type { EntrySize } from '@terrafirmagreg-team/game/types/entry';
+
+const GAME_ICON = 12.8;
+const STACK_SCALE = 1.15;
+
+function memberRef(
+  member: string | TaggedReference,
+  kind: ReferenceKind,
+): TaggedReference | undefined {
+  return typeof member === 'string' ? classifyRefId(member, kind) : member;
+}
+
+function memberKey(member: string | TaggedReference, kind: ReferenceKind): string {
+  const ref = memberRef(member, kind);
+  return ref ? `${ref.kind}:${stackIdFromRef(ref)}` : String(member);
+}
+
+async function expandTagRefs(
+  refs: readonly TaggedReference[],
+  dataset: DatasetRef,
+): Promise<TaggedReference[]> {
+  const groups = await Promise.all(
+    refs.map((ref) =>
+      isTagKind(ref.kind)
+        ? fetchTagMembers(dataset, ref.id, tagKindOf(ref.kind) ?? 'item')
+        : null,
+    ),
+  );
+  const seen = new Set<string>();
+  const out: TaggedReference[] = [];
+  refs.forEach((ref, i) => {
+    const memberIds = groups[i];
+    const memberKind = tagKindOf(ref.kind) ?? 'item';
+    const expanded: TaggedReference[] = memberIds
+      ? memberIds.map((id) => ({ kind: memberKind, id }))
+      : [ref];
+    for (const member of expanded) {
+      const key = `${member.kind}:${stackIdFromRef(member)}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push(member);
+    }
+  });
+  return out;
+}
+
+export const GROUP_CYCLE_MS = ENTRY_CYCLE_MS;
+
+export function EntryGroup({
+  members,
+  kind = 'item',
+  size = 36,
+  chip = true,
+  dataset,
+  limit = 3,
+  cycle,
+  missing = 'hide',
+}: {
+  members: readonly (string | TaggedReference)[];
+  kind?: ReferenceKind;
+  size?: EntrySize;
+  chip?: boolean;
+  dataset?: DatasetRef;
+  limit?: number;
+  cycle?: number;
+  missing?: 'placeholder' | 'item' | 'hide';
+}) {
+  const sizePx = entrySizePx(size);
+  const references = members
+    .map((member) => memberRef(member, kind))
+    .filter((ref): ref is TaggedReference => ref !== undefined);
+  const expandKey =
+    cycle !== undefined &&
+    dataset &&
+    references.some((ref) => isTagKind(ref.kind))
+      ? `${dataset.id}/${dataset.version ?? ''}|${references
+          .map((ref) => `${ref.kind}:${stackIdFromRef(ref)}`)
+          .join('|')}`
+      : null;
+  const expandedHit = useAsyncResult(
+    expandKey
+      ? async () => ({
+          key: expandKey,
+          refs: await expandTagRefs(references, dataset!),
+        })
+      : false,
+    [expandKey, dataset],
+  );
+  const cycleRefs = !expandKey
+    ? references
+    : expandedHit.value?.key === expandKey
+      ? expandedHit.value.refs
+      : references;
+  const [index] = useCycleIndex(cycleRefs.length, {
+    enabled: cycle !== undefined && cycle > 0,
+    intervalMs: cycle,
+  });
+  if (cycle !== undefined) {
+    return (
+      <span
+        className="relative block"
+        style={{ width: sizePx, height: sizePx }}
+      >
+        {cycleRefs.map((reference, i) => (
+          <span
+            key={`${reference.kind}:${stackIdFromRef(reference)}`}
+            className="absolute inset-0"
+            style={{ opacity: i === index ? 1 : 0 }}
+            aria-hidden={i !== index}
+          >
+            <EntryIcon
+              reference={reference}
+              dataset={dataset}
+              size={sizePx}
+              missing={missing}
+            />
+          </span>
+        ))}
+      </span>
+    );
+  }
+  const scale =
+    (sizePx - (chip ? SPRITE_CLUSTER_INSET : 0)) / SPRITE_CLUSTER_UNITS;
+  return (
+    <SpriteCluster
+      size={sizePx}
+      chip={chip}
+      limit={limit}
+      items={members.slice(0, limit).map((member) => (
+        <EntryIcon
+          key={memberKey(member, kind)}
+          reference={memberRef(member, kind)}
+          dataset={dataset}
+          size={GAME_ICON * STACK_SCALE * scale}
+          missing={missing}
+        />
+      ))}
+    />
+  );
+}
+