@citisen/litearea 0.1.0 → 0.2.1

package/scripts/verify-package.mjs

@@ -26,15 +26,17 @@ const packageJson = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'))
  * Every entry point `package.json` promises, and where its declarations landed.
  *
  * The declarations come from `tsc` rather than from the JavaScript bundler, so they
- * mirror the source tree: the root entry is one file, while `react` and `grammars`
- * are directories with an `index.d.ts` in them. That extra level is the price of not
- * depending on a declaration bundler that predates TypeScript 7, and it is encoded
- * here so a change to the layout cannot pass unnoticed.
+ * mirror the source tree: the root entry is one file, while `react` is a directory
+ * with an `index.d.ts` in it. That extra level is the price of not depending on a
+ * declaration bundler that predates TypeScript 7, and it is encoded here so a change
+ * to the layout cannot pass unnoticed.
+ *
+ * There is deliberately no `grammars` entry: the library ships no syntax, so it
+ * publishes no grammar for a host to import and none for this verifier to borrow.
  */
 const ENTRIES = [
   { name: 'index', declarations: 'types/index.d.ts' },
   { name: 'react', declarations: 'types/react/index.d.ts' },
-  { name: 'grammars', declarations: 'types/grammars/index.d.ts' },
   { name: 'styles', declarations: 'types/styles.d.ts' },
 ]
 
@@ -74,17 +76,6 @@ const CORE_EXPORTS = [
   'canEditThroughPipeline',
 ]
 
-/** The names the grammars entry must export. */
-const GRAMMAR_EXPORTS = [
-  'dshFontQueryGrammar',
-  'dshSentryStyleGrammar',
-  'fontWeightWord',
-  'fontFaceWeights',
-  'quoteFontFamily',
-  'FONT_WEIGHT_WORDS',
-  'FONT_GENERIC_FAMILIES',
-]
-
 /** The names the React entry must export. */
 const REACT_EXPORTS = ['LiteAreaEditor']
 
@@ -171,30 +162,63 @@ const core = await import(pathToFileURL(join(dist, 'index.js')).href)
 const missing = CORE_EXPORTS.filter((name) => core[name] === undefined)
 if (missing.length > 0) fail(`index.js does not export: ${missing.join(', ')}`)
 
-const grammars = await import(pathToFileURL(join(dist, 'grammars.js')).href)
-const missingGrammars = GRAMMAR_EXPORTS.filter((name) => grammars[name] === undefined)
-if (missingGrammars.length > 0) fail(`grammars.js does not export: ${missingGrammars.join(', ')}`)
-
 const react = await import(pathToFileURL(join(dist, 'react.js')).href)
 const missingReact = REACT_EXPORTS.filter((name) => react[name] === undefined)
 if (missingReact.length > 0) fail(`react.js does not export: ${missingReact.join(', ')}`)
 
 // ── the engine works from the built artifact, not just from source ─────────
+//
+// The grammar below is a FIXTURE and lives only in this file. The package ships
+// no syntax, so there is nothing to import: a verifier that borrowed a language
+// from somewhere else would be checking that language rather than the artifact
+// it is here to check. Two rules and one vocabulary are enough to prove the
+// built engine still tokenizes, diagnoses, completes, and segments.
+
+/** A closed set of shapes, small enough to read at a glance. */
+const SHAPES = core.defineVocabulary({
+  id: 'shape',
+  words: ['circle', 'square'],
+  unknownMessage: '"{word}" is not a shape — expected {allowed}.',
+  docs: { circle: { detail: 'a disc', body: 'Verifier fixture documentation.' } },
+})
+
+/** The whole language: one keyword, one vocabulary, one completion source. */
+const fixture = core.defineGrammar({
+  id: 'verify-fixture',
+  rules: [
+    { kind: 'match', scope: 'keyword', pattern: /draw/ },
+    { kind: 'words', words: SHAPES, unknown: {} },
+  ],
+  compose: [
+    {
+      id: 'shape',
+      range: (context) => context.word,
+      items: () =>
+        ['circle', 'square'].map((shape) => ({
+          label: shape,
+          append: ' ',
+          kind: 'shape',
+          detail: SHAPES.entryFor(shape)?.detail,
+        })),
+    },
+  ],
+})
 
-const grammar = grammars.dshSentryStyleGrammar()
-const inspection = core.inspect('running  circle  blue  turn   3\nbogus circle', grammar)
+const inspection = core.inspect('draw circle\nbogus square', fixture)
 assert.ok(inspection.tokens.length > 0, 'the built engine produced no tokens')
 assert.ok(
-  inspection.diagnostics.some((diagnostic) => diagnostic.code === 'vocabulary:state'),
-  'the built engine did not report the unknown state',
+  inspection.diagnostics.some((diagnostic) => diagnostic.code === 'vocabulary:shape'),
+  'the built engine did not report the unknown shape',
 )
-const completion = core.complete(inspection, grammar, {
-  text: 'running ',
-  caret: 'running '.length,
+const completion = core.complete(core.inspect('draw ', fixture), fixture, {
+  text: 'draw ',
+  caret: 'draw '.length,
   trigger: 'explicit',
 })
 assert.ok(completion !== undefined, 'the built engine offered no completion')
 assert.ok(completion.rows.length > 0, 'the built engine offered an empty completion')
+assert.equal(completion.sourceId, 'shape', 'the built engine opened the wrong completion source')
+assert.equal(completion.rows[0]?.item.append, ' ', 'the built engine dropped a row field')
 
 const segments = core.buildSegments(inspection.text, inspection)
 assert.equal(

package/src/core/types.ts

@@ -67,9 +67,9 @@ export interface Token extends Range {
  * tokens and they are deliberately not tokens here.
  *
  * The distinction earns its keep. A token is what the *characters* are; a
- * decoration is what they *mean*, and the two change on different schedules. The
- * font-query grammar paints `Geist Mono` as a family from the characters alone,
- * but which family is *in effect* depends on the installed catalogue — the same
+ * decoration is what they *mean*, and the two change on different schedules. A
+ * grammar can paint `Geist Mono` as a family from the characters alone, but which
+ * family is *in effect* depends on a catalogue the HOST supplied — the same
  * characters mean something else on another machine. Painting that as a token
  * would mean re-lexing the document whenever the catalogue changed; painting it
  * as a decoration means recomputing one range list, which is what it is.
@@ -493,8 +493,8 @@ export interface CompletionContext<State = unknown> {
    * `runn|` is no longer "at the start of the line" in the strict sense, but it is
    * unmistakably completing the first word. A source that asked `firstOnLine` would
    * switch itself off after the very first keystroke — which is exactly the bug this
-   * field was added to fix, and exactly the kind of thing a reference grammar is
-   * for finding.
+   * field was added to fix, and exactly the kind of thing a grammar written against
+   * a real document is for finding.
    */
   firstWord: boolean
   /** The first non-whitespace token on the caret's line, when there is one. */

package/src/dom/editor.ts

@@ -94,9 +94,14 @@ export interface LiteAreaCompletion {
   /**
    * Characters that open the list in addition to word characters.
    *
-   * Default `' '`, and that default is doing real work: both reference languages
-   * put a value after a name, so a space is exactly where the next word becomes
-   * guessable.
+   * Empty by default, because a separator is the wrong moment to interrupt: it is
+   * where the next token starts, which is the argument FOR opening there, and it
+   * loses to the habit every reader already has — the editor this is modelled on
+   * offers nothing on a space and waits for a letter or for `Ctrl+Space`. Nothing
+   * is stranded by that. The list stays open once it is open, so a value typed
+   * after a name is still filtered in place, and `Ctrl+Space` opens it on demand.
+   * Set it to `' '` or `','` for a language where a separator really is where the
+   * next token becomes guessable.
    */
   triggerCharacters?: string
   /** The most rows to offer. Default 100. */
@@ -289,11 +294,16 @@ export class LiteArea<State = unknown> {
       { autoGrow: true, minRows: 1 },
       options.sizing as Partial<ResolvedSizing> | undefined,
     )
+    // A word character opens the list; a separator does not, unless the grammar's
+    // host asks for one by name. The list does not need a separator to be helpful
+    // — it is already open while the next token is typed, and it re-filters in
+    // place — and opening on a space spends the one keystroke a reader is least
+    // willing to have interrupted.
     this.completion =
       options.completion === false
         ? undefined
         : withDefaults<ResolvedCompletion>(
-            { auto: true, triggerCharacters: ' ', limit: 100, showDocumentation: true },
+            { auto: true, triggerCharacters: '', limit: 100, showDocumentation: true },
             options.completion,
           )
     this.hover =

package/src/index.ts

@@ -6,12 +6,13 @@
 //
 // The package has three entry points and this is the largest:
 //
-//   @citisen/litearea            the engine and the DOM layer (this file)
-//   @citisen/litearea/react      a React binding over the same editor
-//   @citisen/litearea/grammars   two worked grammars for two real DSLs
+//   @citisen/litearea              the engine and the DOM layer (this file)
+//   @citisen/litearea/react        a React binding over the same editor
+//   @citisen/litearea/styles.css   the stylesheet, for hosts that link CSS
 //
-// Nothing here knows any syntax. `src/core/` is pure and needs no DOM; `src/dom/`
-// needs a document and no framework.
+// Nothing here knows any syntax, and the package ships none: a caller supplies
+// the rules. `src/core/` is pure and needs no DOM; `src/dom/` needs a document
+// and no framework.
 
 export type {
   CheckRule,