+++

stack--current/3-advanced--multi/rich-text-format/doc/demo-node/index.mjs

@@ -10,7 +10,7 @@ import {
 	DOC_DEMO_RPG_02,
 	DOC_DEMO_RPG_03,
 	DOC_DEMO_INVENTORY,
-} from '../examples.mjs'
+} from '@offirmo-private/rich-text-format/examples'
 
 import renderⵧto_terminal from '../../../rich-text-format--to-terminal/index.mjs'
 

stack--current/3-advanced--multi/rich-text-format/package.json

@@ -12,6 +12,8 @@
 		".": {
 			"import": "./dist/src.es2023.esm/index.js",
 			"require": "./dist/src.es2023.cjs/index.js"
+		"./examples": {
+			"import": "./dist/src.es2023.esm/examples/index.js"
 		},
 		"./styles.css": "./src/renderers/style.css"
 	},
@@ -31,6 +33,7 @@
 
 	"scripts": {
 		"clean": "monorepo-script--clean-package …dist",
+
 		"_build:dev:watch": "monorepo-script--build-typescript-package --watch",
 		"_build:prod": "monorepo-script--build-typescript-package",
 

stack--current/3-advanced--multi/rich-text-format/doc/examples.mjs → stack--current/3-advanced--multi/rich-text-format/src/examples/index.ts

@@ -1,14 +1,14 @@
-import * as RichText from '@offirmo-private/rich-text-format'
+import * as RichText from '..'
 
 /////// parts ///////
 
-const SUB_UL_ITEMS = {
+const SUB_UL_ITEMS: RichText.Document['$sub'] = {
 	'002': {$type: 'fragmentⵧinline', $content: 'ul #2'},
 	'001': {$type: 'fragmentⵧinline', $content: 'ul #1'},
 	'003': {$type: 'fragmentⵧinline', $content: 'ul #3'},
 }
 
-const SUB_UL_KEY_VALUE_PAIRS = {
+const SUB_UL_KEY_VALUE_PAIRS: RichText.Document['$sub'] = {
 	'001': {
 		$type: 'fragmentⵧinline',
 		$content: '⎨⎨key⎬⎬: ⎨⎨value⎬⎬',
@@ -47,7 +47,7 @@ const SUB_UL_KEY_VALUE_PAIRS = {
 	},
 }
 
-const DOC_WEAPON_01_NAME = {
+const DOC_WEAPON_01_NAME: RichText.Document = {
 	$classes: ['item--name', 'item--weapon--name'],
 	$content: '⎨⎨qualifier2|Capitalize⎬⎬ ⎨⎨qualifier1|Capitalize⎬⎬ ⎨⎨base|Capitalize⎬⎬',
 	$sub: {
@@ -66,7 +66,7 @@ const DOC_WEAPON_01_NAME = {
 	},
 }
 
-const DOC_WEAPON_01 = {
+const DOC_WEAPON_01: RichText.Document = {
 	$type: 'fragmentⵧinline',
 	$classes: ['item', 'item--weapon', 'item--quality--legendary'],
 	$content: '⎨⎨weapon_name⎬⎬ ⎨⎨enhancement⎬⎬',
@@ -83,7 +83,7 @@ const DOC_WEAPON_01 = {
 	},
 }
 
-const DOC_PLACE_01 = {
+const DOC_PLACE_01: RichText.Document = {
 	$type: 'fragmentⵧinline',
 	$classes: ['place'],
 	$content: 'the country of ⎨⎨name⎬⎬',
@@ -98,7 +98,7 @@ const DOC_PLACE_01 = {
 	},
 }
 
-const DOC_NPC_01 = {
+const DOC_NPC_01: RichText.Document = {
 	$type: 'fragmentⵧinline',
 	$classes: ['person', 'npc', 'monster--rank--boss'],
 	$content: 'John Smith',
@@ -111,7 +111,7 @@ const DOC_NPC_01 = {
 function render_item(i) {
 	return render_item_short(i)
 }*/
-const SUB_UL_ACTIONABLE_ITEMS = {
+const SUB_UL_ACTIONABLE_ITEMS: RichText.Document['$sub'] = {
 	'001': DOC_WEAPON_01,
 	/*'002': render_item(DEMO_WEAPON_1),
 	'003': render_item(DEMO_ARMOR_1),
@@ -121,7 +121,7 @@ const SUB_UL_ACTIONABLE_ITEMS = {
 
 /////// COMPLETE DOCS ///////
 
-const DOC_DEMO_BASE_TYPES = {
+const DOC_DEMO_BASE_TYPES: RichText.Document = {
 	$type: 'fragmentⵧinline',
 	$classes: [],
 	$content: '⎨⎨fragment1⎬⎬⎨⎨fragment2⎬⎬',
@@ -173,7 +173,7 @@ const DOC_DEMO_BASE_TYPES = {
 	},
 }
 
-const DOC_DEMO_ADVANCED_TYPES = {
+const DOC_DEMO_ADVANCED_TYPES: RichText.Document = {
 	$type: 'fragmentⵧinline',
 	$classes: [],
 	$content: '⎨⎨heading⎬⎬Key-value pairs:⎨⎨kvdefault⎬⎬Nested list:⎨⎨nested_list⎬⎬Actionable items:⎨⎨uuid_list⎬⎬Done.',
@@ -243,7 +243,7 @@ const DOC_DEMO_ADVANCED_TYPES = {
 	},
 }
 
-const DOC_DEMO_HINTS = {
+const DOC_DEMO_HINTS: RichText.Document = {
 	$type: 'fragmentⵧinline',
 	$classes: [],
 	$content: '⎨⎨heading⎬⎬link: ⎨⎨link⎬⎬⎨⎨br⎬⎬List with no bullets:⎨⎨list⎬⎬Done.',
@@ -269,7 +269,7 @@ const DOC_DEMO_HINTS = {
 	},
 }
 
-const DOC_DEMO_RPG_01 = {
+const DOC_DEMO_RPG_01: RichText.Document = {
 	$v: 1,
 	$type: 'fragmentⵧblock',
 	$content: 'You are in ⎨⎨place⎬⎬. You meet ⎨⎨npc⎬⎬.⎨⎨br⎬⎬He gives you a ⎨⎨item⎬⎬.⎨⎨hr⎬⎬',
@@ -280,7 +280,7 @@ const DOC_DEMO_RPG_01 = {
 	},
 }
 
-const DOC_DEMO_RPG_02 = {
+const DOC_DEMO_RPG_02: RichText.Document = {
 	$v: 1,
 	$type: 'ol',
 	$sub: {
@@ -299,10 +299,10 @@ const DOC_DEMO_RPG_03 = RichText.fragmentⵧblock()
 	)
 	.pushStrong('A great saga just started.')
 	.pushText('⎨⎨br⎬⎬loot:')
-	.pushNode(DOC_DEMO_RPG_02, 'loot')
+	.pushRawNode(DOC_DEMO_RPG_02, { id: 'loot' })
 	.done()
 
-const DOC_DEMO_INVENTORY = {
+const DOC_DEMO_INVENTORY: RichText.Document = {
 	'$v': 1,
 	'$type': 'fragmentⵧblock',
 	'$classes': [],

stack--current/3-advanced--multi/rich-text-format/src/index.ts

@@ -4,8 +4,8 @@ export * from './renderers/to_actions.js'
 export * from './renderers/to_text.js'
 export * from './renderers/to_html.js'
 
-export * from './types.js'
-export * from './type-guards.js'
+export * from './types/index.js'
+export * from './types/guards.js'
 export * from './walk.js'
 export * from './renderers/common.js'
 export * from './sugar/builder.js'

stack--current/3-advanced--multi/rich-text-format/src/renderers/common.ts

@@ -1,6 +1,6 @@
 import {
 	type CheckedNode,
-} from '../types.js'
+} from '../types/index.js'
 
 /////////////////////////////////////////////////
 

stack--current/3-advanced--multi/rich-text-format/src/renderers/to_actions.ts

@@ -10,7 +10,7 @@ import {
 	type WalkerCallbacks,
 	type WalkerReducer,
 } from '../walk.js'
-import { type CheckedNode, type NodeLike } from '../types.js'
+import { type CheckedNode, type NodeLike } from '../types/index.js'
 
 /////////////////////////////////////////////////
 

stack--current/3-advanced--multi/rich-text-format/src/renderers/to_debug.ts

@@ -3,7 +3,7 @@
 import {
 	type CheckedNode,
 	type Node,
-} from '../types.js'
+} from '../types/index.js'
 
 import {
 	WalkerCallbacks,

stack--current/3-advanced--multi/rich-text-format/src/renderers/to_html.ts

@@ -8,7 +8,7 @@ import {
 	type WalkerCallbacks,
 	type WalkerReducer,
 } from '../walk.js'
-import { type CheckedNode, type Node } from '../types.js'
+import { type CheckedNode, type Node } from '../types/index.js'
 
 import { isꓽlist, isꓽlink, isꓽlistⵧKV, isꓽlistⵧuuid } from './common.js'
 

stack--current/3-advanced--multi/rich-text-format/src/renderers/to_text.ts

@@ -1,4 +1,4 @@
-import { type Node, type CheckedNode } from '../types.js'
+import { type Node, type CheckedNode } from '../types/index.js'
 import { NODE_TYPE_to_DISPLAY_MODE } from '../consts.js'
 import {
 	type BaseRenderingOptions,

stack--current/3-advanced--multi/rich-text-format/src/sugar/builder.ts

@@ -6,7 +6,7 @@ import {
 	type CheckedNode,
 	type Node,
 	type Document,
-} from '../types.js'
+} from '../types/index.js'
 import { promoteꓽto_node } from '../utils/promote.js'
 
 /////////////////////////////////////////////////

stack--current/3-advanced--multi/rich-text-format/src/type-guards.ts → stack--current/3-advanced--multi/rich-text-format/src/types/guards.ts

@@ -1,8 +1,8 @@
 import assert from 'tiny-invariant'
 import { type Immutable } from '@offirmo-private/ts-types'
 
-import { LIB } from './consts.js'
-import { type Node } from './types.js'
+import { LIB } from '../consts.js'
+import { type Node } from './index.js'
 
 /////////////////////////////////////////////////
 
@@ -14,9 +14,9 @@ const EXPECTED_FIELDS = new Set<string>([
 	'$sub',
 	'$hints',
 ])
-function assertꓽisꓽNode(node: Immutable<any>): asserts node is Node {
+function assertꓽisꓽNode(candidate: Immutable<any>): asserts candidate is Node {
 	// "Node" is quite loose so we only expect at least 1 param
-	const keys = Object.keys(node)
+	const keys = Object.keys(candidate)
 	keys.forEach(k => {
 		assert(EXPECTED_FIELDS.has(k), `${LIB}: a Node should not contain extraneous fields! ("${k}")`)
 	})

stack--current/3-advanced--multi/rich-text-format/src/type-guards_spec.ts → stack--current/3-advanced--multi/rich-text-format/src/types/guards_spec.ts

@@ -1,8 +1,8 @@
 import { expect } from 'chai'
 
-import { LIB } from './consts.js'
+import { LIB } from '../consts.js'
 
-import { isꓽNode } from './type-guards.js'
+import { isꓽNode } from './guards.js'
 
 /////////////////////////////////////////////////
 

stack--current/3-advanced--multi/rich-text-format/src/types.ts → stack--current/3-advanced--multi/rich-text-format/src/types/index.ts

@@ -17,11 +17,13 @@ const NodeType = Enum(
 	'ol',
 	'ul',
 	'hr',
+	'emoji', // unfortunately, as of 2024, emojis are still very hard to handle properly, hence deserving a special node type (optional but recommended)
+	         // this node type represent a single emoji
 
 	// special
-	'br',
+	'br', // do not abuse, use other semantic elements (heading, lists) as much as possible before this one
 
-	// internally used, don't mind, don't use directly
+	// internally used, don't use directly
 	'li',
 )
 type NodeType = Enum<typeof NodeType> // eslint-disable-line no-redeclare
@@ -32,7 +34,8 @@ type NodeType = Enum<typeof NodeType> // eslint-disable-line no-redeclare
 interface Hints {
 	[k: string]: any
 
-	bullets_style?: 'none' // to remove bullets from lists
+	bullets_style?: 'none' // for ul, to remove or customize bullets
+
 
 	// TODO clarify
 	// known:

stack--current/3-advanced--multi/rich-text-format/src/types_spec.ts → stack--current/3-advanced--multi/rich-text-format/src/types/index_spec.ts

@@ -1,10 +1,10 @@
 import { expect } from 'chai'
 
-import { LIB } from './consts.js'
+import { LIB } from '../consts.js'
 
 import {
 	Node,
-} from './types.js'
+} from './index.js'
 
 /////////////////////////////////////////////////
 

stack--current/3-advanced--multi/rich-text-format/src/utils/normalize.ts

@@ -7,7 +7,7 @@ import {
 	type Hints,
 	type CheckedNode,
 	type Node,
-} from '../types.js'
+} from '../types/index.js'
 
 /////////////////////////////////////////////////
 

stack--current/3-advanced--multi/rich-text-format/src/utils/promote.ts

@@ -4,8 +4,8 @@ import {
 	NodeType,
 	type NodeLike,
 	type Node,
-} from '../types.js'
-import { assertꓽisꓽNode } from '../type-guards.js'
+} from '../types/index.js'
+import { assertꓽisꓽNode } from '../types/guards.js'
 
 /////////////////////////////////////////////////
 
@@ -19,8 +19,9 @@ function promoteꓽto_node($raw: NodeLike): Node {
 			$content: $raw,
 		}
 
-	// it could be anything bc Node is very lax, better check
+	// it could be anything bc type Node is very lax, better check
 	assertꓽisꓽNode($raw)
+
 	return $raw
 }
 

stack--current/3-advanced--multi/rich-text-format/src/walk.ts

@@ -6,7 +6,7 @@ import {
 	NodeType,
 	type CheckedNode,
 	type Node,
-} from './types.js'
+} from './types/index.js'
 
 import { normalizeꓽnode } from './utils/normalize.js'
 

stack--current/3-advanced/utils--state/README.md

@@ -12,6 +12,8 @@ import {
 	BaseRootState,
 	complete_or_cancel_eager_mutation_propagating_possible_child_mutation,
 } from '@offirmo-private/state-utils'
+
+import { getꓽmutable_copy } from '@offirmo-private/state-utils'
 ```
 
 ## Concepts

stack--current/5-incubator/active--no-pkg/bite-sized/lists/senior-dev/tech-bites--concepts.md

@@ -29,9 +29,10 @@
 [ ] patterns https://www.patterns.dev/
 [ ] SWE at Google https://abseil.io/resources/swe-book/html/toc.html
 [ ] technical things every software developer should know https://github.com/mtdvio/every-programmer-should-know
+abort controller https://kettanaito.com/blog/dont-sleep-on-abort-controller
 abstraction https://www.merrickchristensen.com/articles/abstraction/
 access control
-access control -- Role-Based (RBAC)
+access control -- role-based (RBAC)
 actually portable executables https://justine.lol/ape.html
 allocation
 annotation
@@ -169,8 +170,9 @@ design patterns
 design patterns -- behavioral -- command = command, receiver, invoker and client https://en.wikipedia.org/wiki/Command_pattern
 design patterns -- facade https://en.wikipedia.org/wiki/Facade_pattern
 design patterns -- strangler https://paulhammant.com/2013/07/14/legacy-application-strangulation-case-studies/
+design patterns -- visitor (not recommended, see grug)
 design smell https://en.wikipedia.org/wiki/Design_smell
-devex
+DevEx
 DevOps https://www.browserstack.com/guide/difference-between-continuous-integration-and-continuous-delivery
 DevOps Research and Assessment (DORA) = how we should develop our software right and what numbers we should show to our managers to make them happy https://medium.com/booking-com-development/a-step-by-step-guide-on-how-not-to-implement-dora-metrics-85081f0d4484
 DNS (Domain Name System)

stack--current/5-incubator/active--no-pkg/bite-sized/lists/senior-dev/tech-bites--frontend-web.md

@@ -16,7 +16,6 @@
 [ ] security https://portswigger.net/web-security/all-topics
 [ ] security https://xsleaks.dev/
 [ ] TODO shearing layers https://en.wikipedia.org/wiki/Shearing_layers
-abort controller https://kettanaito.com/blog/dont-sleep-on-abort-controller
 AJAX (Asynchronous JavaScript And XML) = LEGACY interactive web apps now fetch + json
 AMP (Accelerated Mobile Pages)
 animations -- API https://devdocs.io/dom/web_animations_api

stack--current/A-apps--core/the-boring-rpg/x-sandbox/src/hateoas/server.ts

@@ -37,7 +37,6 @@ import { resolveꓽrich_text_pending_engagement } from '../to-export-to-own-pack
 
 const DEBUG = false
 
-
 class AppHateoasServer implements HATEOASServer<HypermediaContentType, Action> {
 	app_sugar: Game = new Game()
 	pending_async: Array<Promise<void>> = []
@@ -57,7 +56,7 @@ class AppHateoasServer implements HATEOASServer<HypermediaContentType, Action> {
 			rel: ['self'],
 			cta: '…', // can be re-defined later
 		}
-		// const hyperlinkꘌhome: Hyperlink NO! Should be a feature of the browser!
+		// const hyperlinkꘌhome: Hyperlink // NO! Should be a feature of the browser!
 		const links: { [key: string]: Hyperlink } = {
 			self: hyperlinkꘌself,
 		}
@@ -122,6 +121,7 @@ class AppHateoasServer implements HATEOASServer<HypermediaContentType, Action> {
 			}
 
 			case '/session': { // for recap
+				// TODO review should be engagement instead?
 				$builder = $builder.pushNode(AppRichText.getꓽrecap(state.u_state))
 
 				const hyperlinkꘌcontinue_to: Hyperlink = {