diff --git a/projects/typed-peripheral-digitalitems/documentation/guides/advanced-items.md b/projects/typed-peripheral-digitalitems/documentation/guides/advanced-items.md index f245942..42faf03 100644 --- a/projects/typed-peripheral-digitalitems/documentation/guides/advanced-items.md +++ b/projects/typed-peripheral-digitalitems/documentation/guides/advanced-items.md @@ -1,9 +1,21 @@ -# Advanced Items +--- +peripheralInterface: AdvancedDigitizer +--- + +# Advanced Digitizer + +
+
Advanced digitizer block
+
MULTI-STORAGE PERIPHERAL

The advanced digitizer moves items, fluids, and energy between attached storage and durable digital identifiers.

Peripheral type
advanced_digitizer
Storage
Items, fluids, energy
Failure style
Recoverable result pairs
+
The advanced digitizer can extract from its internal inventory with source `self`, or from an attached inventory/item storage by peripheral name. The source defaults to `self`. +> **Mode matters:** an identifier belongs to exactly one of `item`, `fluid`, or +> `energy`. Always use the same mode when inspecting, refreshing, or restoring it. + Item filters may be: - A one-based slot number. This requires slotted storage. diff --git a/projects/typed-peripheral-digitalitems/documentation/guides/basic-digitizer.md b/projects/typed-peripheral-digitalitems/documentation/guides/basic-digitizer.md index 8ce2709..b3eb5c6 100644 --- a/projects/typed-peripheral-digitalitems/documentation/guides/basic-digitizer.md +++ b/projects/typed-peripheral-digitalitems/documentation/guides/basic-digitizer.md @@ -1,8 +1,20 @@ +--- +peripheralInterface: Digitizer +--- + # Basic Digitizer -The basic digitizer handles items in its own inventory. Slots are one-based and -default to slot 1. `digitize()` removes the complete stack; `digitizeAmount()` -requires an exact positive amount no greater than the physical stack. +
+
Digitizer block
+
ITEM PERIPHERAL

The basic digitizer turns physical item stacks into portable digital identifiers and restores them through its internal inventory.

Peripheral type
digitizer
Storage
Items
Failure style
Lua errors
+
+ +Slots are one-based and default to slot 1. `digitize()` removes the complete +stack; `digitizeAmount()` requires an exact positive amount no greater than the +physical stack. + +> **Inherited inventory API:** `size`, `list`, `getItemDetail`, `getItemLimit`, +> `pushItems`, and `pullItems` are also available on this peripheral. ## Round trip a partial stack @@ -29,6 +41,8 @@ local inserted = digitizer.rematerializeAmount(id, 8) print("Inserted " .. inserted) ``` +## Errors and remaining items + All failures throw. Empty slots, non-positive amounts, requesting more than the physical or digital count, and unknown or decayed identifiers are errors. diff --git a/projects/typed-peripheral-digitalitems/documentation/index.md b/projects/typed-peripheral-digitalitems/documentation/index.md index e992658..c3dd707 100644 --- a/projects/typed-peripheral-digitalitems/documentation/index.md +++ b/projects/typed-peripheral-digitalitems/documentation/index.md @@ -1,16 +1,27 @@ -# Digital Items Typed Peripheral API +# Digital Items Peripheral Manual -This package supplies TypeScriptToLua declarations and peripheral providers for -Digital Items 3. It covers the item-only `digitizer` and the multi-storage -`advanced_digitizer` peripherals. +Player-focused documentation and typed APIs for the Digital Items 3 peripherals. +Use these pages whether you write programs directly in CraftOS Lua or compile +TypeScript with TypeScriptToLua. -## Choose a peripheral +## Choose your digitizer -- Use the basic digitizer for simple item workflows through its internal inventory. -- Use the advanced digitizer to address remote item, fluid, or energy storage, merge content into existing identifiers, and handle recoverable failures. -- Both peripherals inherit inventory methods. The advanced digitizer additionally reports decay and stack limits through `getConfiguration()`. +
+ + Digitizer block + DigitizerPeripheral type: digitizerDigitize and restore items through a simple internal inventory.Open peripheral guide → + + + Advanced digitizer block + Advanced DigitizerPeripheral type: advanced_digitizerMove items, fluids, and energy between remote storage and digital IDs.Open peripheral guide → + +
-## Documentation +Both peripherals include the standard CC:Tweaked inventory methods. The advanced +digitizer also exposes configured decay and storage limits through +`getConfiguration()`. + +## Start here - [Getting started](getting-started.md) - [Digital identifiers](digital-identifiers.md) @@ -18,6 +29,6 @@ Digital Items 3. It covers the item-only `digitizer` and the multi-storage - [Advanced item guide](guides/advanced-items.md) - [Fluid and energy guide](guides/fluids-and-energy.md) -The generated API reference documents every exported type, method overload, and -provider. Guide examples are shown first in TypeScriptToLua and then in direct -CraftOS Lua. +The **Guides** explain behavior in player terms and include both Lua and +TypeScript examples. The **API reference** is the precise source for signatures, +overloads, return types, and provider declarations. diff --git a/projects/typed-peripheral-digitalitems/documentation/theme/digitalitems.css b/projects/typed-peripheral-digitalitems/documentation/theme/digitalitems.css index 68bb81d..98ecce8 100644 --- a/projects/typed-peripheral-digitalitems/documentation/theme/digitalitems.css +++ b/projects/typed-peripheral-digitalitems/documentation/theme/digitalitems.css @@ -62,6 +62,7 @@ body { .col-content { position: relative; + max-width: 920px; } .col-content::before { @@ -209,6 +210,222 @@ th, td { display: none !important; } +.col-content p, +.col-content li { + max-width: 78ch; +} + +.col-content table { + width: 100%; + border-collapse: collapse; + overflow: hidden; +} + +.col-content th { + color: var(--di-accent-hover); + background: var(--di-bg-elevated); + text-align: left; +} + +.col-content th, +.col-content td { + padding: 0.8rem 1rem; + border-bottom: 1px solid var(--di-border-subtle); + vertical-align: top; +} + +.col-content blockquote { + margin: 1.5rem 0; + padding: 0.8rem 1.1rem; + border-left: 4px solid var(--color-ts-number); + background: color-mix(in srgb, var(--color-ts-number) 7%, var(--di-bg-secondary)); +} + +.col-content blockquote p { + margin: 0; +} + +.di-peripheral-grid { + display: grid; + grid-template-columns: repeat(2, minmax(0, 1fr)); + gap: 1rem; + margin: 1.5rem 0 2rem; +} + +.di-peripheral-card, +.di-peripheral-hero { + border: 1px solid var(--di-border); + background: linear-gradient(145deg, var(--di-bg-elevated), var(--di-bg-secondary)); +} + +.di-peripheral-card { + display: flex; + gap: 1.2rem; + min-height: 190px; + padding: 1.25rem; + border-radius: 10px; + color: var(--color-text); + text-decoration: none; + transition: border-color 160ms ease, transform 160ms ease; +} + +.di-peripheral-card:hover { + border-color: var(--di-accent-hover); + color: var(--color-text); + transform: translateY(-3px); +} + +.di-peripheral-card--advanced, +.di-peripheral-hero--advanced { + border-color: color-mix(in srgb, var(--color-ts-number) 35%, transparent); +} + +.di-peripheral-image { + display: grid; + flex: 0 0 128px; + min-height: 128px; + place-items: center; + border-radius: 6px; + background-color: #0a1114; + background-image: linear-gradient(45deg, rgba(255,255,255,.035) 25%, transparent 25%, transparent 75%, rgba(255,255,255,.035) 75%), linear-gradient(45deg, rgba(255,255,255,.035) 25%, transparent 25%, transparent 75%, rgba(255,255,255,.035) 75%); + background-position: 0 0, 8px 8px; + background-size: 16px 16px; +} + +.di-peripheral-image img { + width: 112px; + height: 112px; + image-rendering: pixelated; +} + +.di-peripheral-copy { + display: flex; + flex-direction: column; +} + +.di-peripheral-copy strong { + font-size: 1.25rem; +} + +.di-peripheral-copy small { + margin: 0.25rem 0 0.75rem; + color: var(--di-text-secondary); +} + +.di-peripheral-copy b { + margin-top: auto; + color: var(--di-accent-hover); + font-size: 0.82rem; +} + +.di-peripheral-hero { + display: grid; + grid-template-columns: 176px minmax(0, 1fr); + gap: 1.75rem; + margin: 1rem 0 2rem; + padding: 1.5rem; + border-radius: 10px; +} + +.di-peripheral-hero .di-peripheral-image { + min-height: 176px; +} + +.di-peripheral-hero .di-peripheral-image img { + width: 144px; + height: 144px; +} + +.di-eyebrow { + color: var(--color-ts-number); + font: 700 0.7rem/1 "Lucida Console", Monaco, monospace; + letter-spacing: 0.12em; +} + +.di-peripheral-hero p { + margin: 0.55rem 0 1rem; + font-size: 1.05rem; +} + +.di-peripheral-hero dl { + display: grid; + grid-template-columns: repeat(3, minmax(0, 1fr)); + gap: 0.7rem; + margin: 0; +} + +.di-peripheral-hero dl div { + min-width: 0; +} + +.di-peripheral-hero dt { + color: var(--di-text-secondary); + font-size: 0.68rem; + text-transform: uppercase; + letter-spacing: 0.06em; +} + +.di-peripheral-hero dd { + margin: 0.2rem 0 0; + overflow-wrap: anywhere; + font-weight: 650; +} + +.di-method-reference { + margin-top: 3rem; +} + +.di-generated-note { + margin-bottom: 1.25rem; + color: var(--di-text-secondary); + font-size: 0.9rem; +} + +.di-method-card { + margin: 1rem 0; + border: 1px solid var(--di-border); + border-radius: 8px; + background: var(--di-bg-secondary); + box-shadow: 0 8px 22px rgba(0, 0, 0, 0.1); + overflow: hidden; +} + +.di-method-card > h3 { + margin: 0; + padding: 0.75rem 1rem; + border-bottom: 1px solid var(--di-border); + background: var(--di-bg-elevated); + color: var(--di-accent-hover); + font-size: 1rem; +} + +.di-method-overload { + padding: 1rem; +} + +.di-method-overload + .di-method-overload { + border-top: 1px dashed var(--di-border); +} + +.di-method-overload .tsd-signature { + margin: 0 0 1rem; + padding: 0.8rem; + box-shadow: none; + overflow-x: auto; +} + +.di-method-overload .tsd-comment { + margin: 0.75rem 0; +} + +.di-method-overload h4 { + margin: 1rem 0 0.35rem; + color: var(--di-text-secondary); + font-size: 0.78rem; + letter-spacing: 0.05em; + text-transform: uppercase; +} + .di-version-panel { margin: 0.5rem 0 1rem; padding: 0.6rem 0.75rem; @@ -332,4 +549,34 @@ footer { max-width: 100%; overflow-x: auto; } + + .di-peripheral-grid { + grid-template-columns: 1fr; + } + + .di-peripheral-hero { + grid-template-columns: 1fr; + } + + .di-peripheral-hero .di-peripheral-image { + min-height: 144px; + } + + .di-peripheral-hero dl { + grid-template-columns: 1fr 1fr; + } +} + +@media (max-width: 480px) { + .di-peripheral-card { + flex-direction: column; + } + + .di-peripheral-image { + flex-basis: auto; + } + + .di-peripheral-hero dl { + grid-template-columns: 1fr; + } } diff --git a/projects/typed-peripheral-digitalitems/documentation/theme/plugin.mjs b/projects/typed-peripheral-digitalitems/documentation/theme/plugin.mjs index 581cc9c..294aa81 100644 --- a/projects/typed-peripheral-digitalitems/documentation/theme/plugin.mjs +++ b/projects/typed-peripheral-digitalitems/documentation/theme/plugin.mjs @@ -1,4 +1,53 @@ -import { JSX } from "typedoc"; +import { JSX, ReflectionKind } from "typedoc"; + +function renderPeripheralMethods(context) { + if (!context.model.isDocument()) return; + + const interfaceName = context.model.frontmatter.peripheralInterface; + if (typeof interfaceName !== "string") return; + + const peripheral = context.page.project + .getReflectionsByKind(ReflectionKind.Interface) + .find((reflection) => reflection.name === interfaceName); + if (!peripheral?.children) return; + + const methods = peripheral.children.filter( + (reflection) => reflection.kindOf(ReflectionKind.Method) && reflection.signatures?.length + ); + if (methods.length === 0) return; + + context.page.pageHeadings.push({ + link: "#peripheral-methods", + text: "Peripheral methods", + level: 2, + }); + + return JSX.createElement( + "section", + { class: "di-method-reference", "aria-labelledby": "peripheral-methods" }, + JSX.createElement("h2", { id: "peripheral-methods" }, "Peripheral methods"), + JSX.createElement( + "p", + { class: "di-generated-note" }, + "Generated from the TypeScript interface. Signatures, parameters, return values, and errors stay synchronized with the published API." + ), + ...methods.map((method) => + JSX.createElement( + "article", + { class: "di-method-card" }, + JSX.createElement("h3", null, method.name), + ...method.signatures.map((signature) => + JSX.createElement( + "div", + { class: "di-method-overload" }, + context.memberSignatureTitle(signature), + context.memberSignatureBody(signature, { hideSources: true }) + ) + ) + ) + ) + ); +} export function load(app) { app.renderer.hooks.on("sidebar.begin", () => @@ -13,4 +62,6 @@ export function load(app) { ) ) ); + + app.renderer.hooks.on("content.end", renderPeripheralMethods); }