@sharpee/text-blocks 1.0.8 → 1.1.1
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.
- package/README.md +72 -0
- package/package.json +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
|