@sharpee/text-blocks 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +72 -0
  2. package/package.json +1 -1
  3. package/types.d.ts +8 -0
  4. package/types.d.ts.map +1 -1
  5. package/types.js.map +1 -1
package/README.md ADDED
@@ -0,0 +1,72 @@
1
+ # @sharpee/text-blocks
2
+
3
+ Pure interfaces for structured text output (`ITextBlock`, `IDecoration`) on the Sharpee Interactive Fiction platform.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ npm install @sharpee/text-blocks
9
+ ```
10
+
11
+ ## Overview
12
+
13
+ - **Types only** - TypeScript interfaces and type guards with no runtime dependencies.
14
+ - **`ITextBlock`** - a unit of structured output carrying a semantic `key` (its channel) and `content`.
15
+ - **`IDecoration`** - decorated content with a fully-resolved CSS class name; per ADR-174 the bracket form `[name:content]` resolves to a `sharpee-`-prefixed class (platform vocabulary) or a bare author class, with no inline styles and no semantic HTML on the wire.
16
+ - **`TextContent`** - either a plain string or an `IDecoration`, nestable for rich content.
17
+ - These interfaces are the contract between the engine prose pipeline (which produces `ITextBlock[]`) and the renderers that route blocks by key to UI regions.
18
+
19
+ ## Usage
20
+
21
+ ```typescript
22
+ import {
23
+ ITextBlock,
24
+ IDecoration,
25
+ TextContent,
26
+ CORE_BLOCK_KEYS,
27
+ isDecoration,
28
+ isStatusBlock,
29
+ extractPlainText,
30
+ } from '@sharpee/text-blocks';
31
+
32
+ // A decorated item name (resolved from `[item:brass lantern]`)
33
+ const item: IDecoration = {
34
+ className: 'sharpee-item',
35
+ content: ['brass lantern'],
36
+ };
37
+
38
+ // An action-result block mixing plain text and decoration
39
+ const block: ITextBlock = {
40
+ key: CORE_BLOCK_KEYS.ACTION_RESULT,
41
+ content: ['You take the ', item, '.'],
42
+ };
43
+
44
+ // Route and inspect blocks
45
+ if (isStatusBlock(block)) {
46
+ // send to the status bar
47
+ }
48
+
49
+ const plain = extractPlainText(block.content); // "You take the brass lantern."
50
+ ```
51
+
52
+ ## Key Exports
53
+
54
+ | Export | Description |
55
+ |--------|-------------|
56
+ | `ITextBlock` | A block of output with a semantic `key` and `content` array |
57
+ | `IDecoration` | Decorated content with a resolved `className` (ADR-174) |
58
+ | `TextContent` | `string \| IDecoration` |
59
+ | `CORE_BLOCK_KEYS` | Platform-defined block keys (`room.name`, `action.result`, etc.) |
60
+ | `BLOCK_KEY_PREFIXES` | Routing prefixes (`status.`, `room.`, `action.`) |
61
+ | `isDecoration`, `isTextBlock`, `isStatusBlock`, `isRoomBlock`, `isActionBlock`, `hasKeyPrefix` | Type guards |
62
+ | `extractPlainText` | Flatten content to a plain string |
63
+
64
+ ## Related Packages
65
+
66
+ - [@sharpee/channel-service](https://www.npmjs.com/package/@sharpee/channel-service) - Carries blocks over channels
67
+ - [@sharpee/core](https://www.npmjs.com/package/@sharpee/core) - Core types and event system
68
+ - [@sharpee/sharpee](https://www.npmjs.com/package/@sharpee/sharpee) - Full platform bundle
69
+
70
+ ## License
71
+
72
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sharpee/text-blocks",
3
- "version": "1.0.0",
3
+ "version": "1.1.0",
4
4
  "description": "Pure interfaces for structured text output (ITextBlock, IDecoration)",
5
5
  "main": "./index.js",
6
6
  "types": "./index.d.ts",
package/types.d.ts CHANGED
@@ -61,6 +61,14 @@ export interface IDecoration {
61
61
  * Can contain nested decorations or plain strings.
62
62
  */
63
63
  readonly content: ReadonlyArray<TextContent>;
64
+ /**
65
+ * Optional value carried by a parameterized decoration (ADR-183) —
66
+ * e.g. the width `%` for `sharpee-center`, the level for
67
+ * `sharpee-indent`. Renderers emit it as a `data-value` attribute,
68
+ * never as an inline style. Absent for non-parameterized decorations.
69
+ * @see ADR-183 §3 — Wire + render
70
+ */
71
+ readonly value?: string;
64
72
  }
65
73
  /**
66
74
  * A block of text output with semantic key (channel).
package/types.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../repos/sharpee/packages/text-blocks/src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,WAAW,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;CAC9C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IAE7C;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAEzB;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe;IAC1B,iBAAiB;;IAEjB,uBAAuB;;IAEvB,4BAA4B;;IAE5B,4BAA4B;;IAE5B,6BAA6B;;IAE7B,gCAAgC;;IAEhC,iCAAiC;;IAEjC,8BAA8B;;IAE9B,mBAAmB;;IAEnB,qBAAqB;;IAErB,yBAAyB;;IAEzB,0BAA0B;;CAElB,CAAC"}
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../repos/sharpee/packages/text-blocks/src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,WAAW,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IAE7C;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IAE7C;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAEzB;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe;IAC1B,iBAAiB;;IAEjB,uBAAuB;;IAEvB,4BAA4B;;IAE5B,4BAA4B;;IAE5B,6BAA6B;;IAE7B,gCAAgC;;IAEhC,iCAAiC;;IAEjC,8BAA8B;;IAE9B,mBAAmB;;IAEnB,qBAAqB;;IAErB,yBAAyB;;IAEzB,0BAA0B;;CAElB,CAAC"}
package/types.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"types.js","sourceRoot":"","sources":["../../../repos/sharpee/packages/text-blocks/src/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAwIH;;;GAGG;AACU,QAAA,eAAe,GAAG;IAC7B,iBAAiB;IACjB,SAAS,EAAE,WAAW;IACtB,uBAAuB;IACvB,gBAAgB,EAAE,kBAAkB;IACpC,4BAA4B;IAC5B,aAAa,EAAE,eAAe;IAC9B,4BAA4B;IAC5B,aAAa,EAAE,eAAe;IAC9B,6BAA6B;IAC7B,cAAc,EAAE,gBAAgB;IAChC,gCAAgC;IAChC,WAAW,EAAE,aAAa;IAC1B,iCAAiC;IACjC,YAAY,EAAE,cAAc;IAC5B,8BAA8B;IAC9B,YAAY,EAAE,cAAc;IAC5B,mBAAmB;IACnB,KAAK,EAAE,OAAO;IACd,qBAAqB;IACrB,MAAM,EAAE,QAAQ;IAChB,yBAAyB;IACzB,YAAY,EAAE,cAAc;IAC5B,0BAA0B;IAC1B,WAAW,EAAE,aAAa;CAClB,CAAC"}
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../../../repos/sharpee/packages/text-blocks/src/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAiJH;;;GAGG;AACU,QAAA,eAAe,GAAG;IAC7B,iBAAiB;IACjB,SAAS,EAAE,WAAW;IACtB,uBAAuB;IACvB,gBAAgB,EAAE,kBAAkB;IACpC,4BAA4B;IAC5B,aAAa,EAAE,eAAe;IAC9B,4BAA4B;IAC5B,aAAa,EAAE,eAAe;IAC9B,6BAA6B;IAC7B,cAAc,EAAE,gBAAgB;IAChC,gCAAgC;IAChC,WAAW,EAAE,aAAa;IAC1B,iCAAiC;IACjC,YAAY,EAAE,cAAc;IAC5B,8BAA8B;IAC9B,YAAY,EAAE,cAAc;IAC5B,mBAAmB;IACnB,KAAK,EAAE,OAAO;IACd,qBAAqB;IACrB,MAAM,EAAE,QAAQ;IAChB,yBAAyB;IACzB,YAAY,EAAE,cAAc;IAC5B,0BAA0B;IAC1B,WAAW,EAAE,aAAa;CAClB,CAAC"}