npm - fragtml - Versions diffs - 0.0.1 → 0.0.3 - Mend

fragtml 0.0.1 → 0.0.3

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 (14) hide show

package/README.md CHANGED Viewed

@@ -156,45 +156,15 @@ html`<button ?disabled="${loading}">Save</button>`
 html`<button ?disabled='${loading}'>Save</button>`
 ```
-## Bound tags
-`html(options)` returns a configured tag. This is useful for fragment rendering and for editor syntax highlighting, because many editors highlight tagged templates better when the tag is a simple identifier.
-```js
-import { createHtml, render } from 'fragtml'
-export function view ({ fragmentId }) {
-  const html = createHtml({ fragmentId })
-  return render(html`
-    <main>...</main>
-  `)
-}
-```
-`createHtml` is an alias of `html`:
-```js
-import html, { createHtml } from 'fragtml'
-createHtml === html
-```
+## Fragments
-You can also use the short fragment-target form:
+Fragments mark named ranges inside a larger template. Calling `html(fragmentId)` on that template renders either the full template or one selected fragment:
-```js
-const html = createHtml('archive-ui')
-```
+- `html()` / `html(undefined)` renders the full template.
+- `html('archive-ui')` renders only the `archive-ui` fragment.
+- `html({ fragmentId: 'archive-ui' })` is the options-object form.
-which is equivalent to:
-```js
-const html = createHtml({ fragmentId: 'archive-ui' })
-```
-## Fragments
-Fragments mark a named range inside a larger template. Rendering without `fragmentId` returns the whole template. Rendering with `fragmentId` returns only that fragment.
+This lets one view function serve both full-page requests and htmx-style fragment requests by passing the requested fragment ID through to `html(fragmentId)`.
 This mirrors the htmx article’s idea:
@@ -215,12 +185,10 @@ ${html.fragment.end}
 ### Example
 ```js
-import { createHtml, render } from 'fragtml'
+import html, { render } from 'fragtml'
 export function contactDetail ({ contact, fragmentId }) {
-  const html = createHtml({ fragmentId })
-  return render(html`
+  return render(html(fragmentId)`
     <html>
       <body>
         <div hx-target="this">
@@ -253,6 +221,51 @@ contactDetail({ contact, fragmentId: 'archive-ui' })
 Fragment boundary tokens are not included in either output.
+If you want a simple local tag name for editor highlighting or repeated use, `frag` is an alias of `html`:
+```js
+import { frag, render } from 'fragtml'
+export function contactDetail ({ contact, fragmentId }) {
+  const html = frag(fragmentId)
+  return render(html`
+    ${html.fragment.start('archive-ui')}
+    <button>${contact.archived ? 'Unarchive' : 'Archive'}</button>
+    ${html.fragment.end}
+  `)
+}
+```
+In TypeScript, you can use an explicit fragment-name union to type-check both incoming fragment IDs and declared fragment boundaries:
+```ts
+import { frag, render } from 'fragtml'
+const contactFragments = {
+  archiveUi: 'archive-ui',
+  details: 'details'
+} as const
+type ContactFragment = typeof contactFragments[keyof typeof contactFragments]
+export function contactDetail ({
+  contact,
+  fragmentId
+}: {
+  contact: Contact
+  fragmentId?: ContactFragment
+}) {
+  const html = frag<ContactFragment>(fragmentId)
+  return render(html`
+    ${html.fragment.start(contactFragments.archiveUi)}
+    <button>${contact.archived ? 'Unarchive' : 'Archive'}</button>
+    ${html.fragment.end}
+  `)
+}
+```
 ### Fragment rules
 - Fragment IDs must be unique within a rendered template.
@@ -266,12 +279,10 @@ Fragment boundary tokens are not included in either output.
 Nested fragments are supported with stack semantics. This is useful when a larger region can be re-rendered as a whole, but a smaller region inside it is also a valid htmx update target.
 ```js
-import { createHtml, render } from 'fragtml'
+import html, { render } from 'fragtml'
 export function page ({ fragmentId }) {
-  const html = createHtml({ fragmentId })
-  return render(html`
+  return render(html(fragmentId)`
     ${html.fragment.start('outer')}
     <section>
       <h2>Outer</h2>
@@ -311,21 +322,21 @@ Safe-by-default template tag.
 html`<p>${value}</p>`
 ```
-Also acts as a factory for bound tags:
+Pass a fragment ID before the tagged template to render a selected fragment from that template:
 ```js
-const h = html({ fragmentId: 'name' })
-const h = html('name')
+html('name')`...`
+html({ fragmentId: 'name' })`...`
 ```
-### `createHtml`
+### `frag`
-Alias of `html`, intended for local tag naming:
+Alias of `html`, useful when you want a local tag name for editor highlighting or repeated use:
 ```js
-import { createHtml } from 'fragtml'
+import { frag } from 'fragtml'
-const html = createHtml({ fragmentId })
+const html = frag(fragmentId)
 ```
 ### `render(value)`

package/index.d.ts CHANGED Viewed

@@ -1,6 +1,6 @@
 export default html;
 import { html } from './lib/html.js';
-export const createHtml: import("./lib/create-tag.js").HtmlTag;
+export const frag: import("./lib/create-tag.js").HtmlTag;
 import { raw } from './lib/raw.js';
 import { render } from './lib/render.js';
 export { html, raw, render };

package/index.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.js"],"names":[],"mappings":";qBAAqB,eAAe;AAIpC~~,+DAAuB~~;~~oBAHH~~,cAAc;uBACX,iBAAiB"}
1	+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.js"],"names":[],"mappings":";qBAAqB,eAAe;AAIpC,yDAAiB;oBAHG,cAAc;uBACX,iBAAiB"}

package/index.js CHANGED Viewed

@@ -2,8 +2,8 @@ import { html } from './lib/html.js'
 import { raw } from './lib/raw.js'
 import { render } from './lib/render.js'
-const createHtml = html
+const frag = html
 export default html
-export { createHtml, html, raw, render }
+export { frag, html, raw, render }
 export { DuplicateFragmentError, FragmentBoundaryError, FragmentNotFoundError } from './lib/render.js'

package/lib/create-tag.d.ts CHANGED Viewed

@@ -5,10 +5,12 @@ export type RenderOptions = {
 export type CompiledTemplate = {
     strings: readonly string[];
 };
-export type HtmlTag = ((strings: TemplateStringsArray | readonly string[], ...substitutions: unknown[]) => HtmlResult) & ((options?: RenderOptions | string) => HtmlTag) & {
+export type HtmlTag = ((strings: TemplateStrings, ...substitutions: HtmlSubstitution[]) => HtmlResult) & ((options?: RenderOptions | string) => HtmlTag) & {
     fragment: FragmentHelpers;
     raw: (value: unknown) => RawHtml;
 };
+import type { TemplateStrings } from './html-types.js';
+import type { HtmlSubstitution } from './html-types.js';
 import { HtmlResult } from './html-result.js';
 import type { FragmentHelpers } from './fragment.js';
 import type { RawHtml } from './raw.js';

package/lib/create-tag.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"create-tag.d.ts","sourceRoot":"","sources":["create-tag.js"],"names":[],"mappings":"~~AA+EA~~,mBADW,OAAO,CACoB;;~~iBArExB~~,MAAM,GAAG,SAAS;;;aAKlB,SAAS,MAAM,EAAE;;~~sBAmElB~~,CAAC,CAAC,OAAO,EAAE,~~oBAAoB~~,~~GAAG,SAAS,MAAM,~~EAAE,~~EAAE,~~GAAG,aAAa,EAAE,~~OAAO~~,EAAE,KAAK,UAAU,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,KAAK,OAAO,CAAC,GAAG;IAAE,QAAQ,EAAE,eAAe,CAAC;IAAC,GAAG,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAA;CAAE;~~2BA9EtM~~,kBAAkB;~~qCAJR~~,eAAe;~~6BACvB~~,UAAU"}
1	+ {"version":3,"file":"create-tag.d.ts","sourceRoot":"","sources":["create-tag.js"],"names":[],"mappings":"AAqFA,mBADW,OAAO,CACoB;;iBA1ExB,MAAM,GAAG,SAAS;;;aAKlB,SAAS,MAAM,EAAE;;sBAwElB,CAAC,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,aAAa,EAAE,gBAAgB,EAAE,KAAK,UAAU,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,KAAK,OAAO,CAAC,GAAG;IAAE,QAAQ,EAAE,eAAe,CAAC;IAAC,GAAG,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAA;CAAE;qCAvF1J,iBAAiB;sCAAjB,iBAAiB;2BAI7C,kBAAkB;qCALR,eAAe;6BAEvB,UAAU"}

package/lib/create-tag.js CHANGED Viewed

@@ -1,4 +1,5 @@
 /** @import { FragmentHelpers } from './fragment.js' */
+/** @import { HtmlSubstitution, TemplateStrings } from './html-types.js' */
 /** @import { RawHtml } from './raw.js' */
 import { createFragmentHelpers } from './fragment.js'
@@ -56,8 +57,11 @@ function normalizeOptions (options) {
  * @returns {HtmlTag}
  */
 function createBoundTag (options) {
-  // eslint-disable-next-line @stylistic/no-extra-parens
-  const tag = /** @type {HtmlTag} */ (function tag (strings, ...substitutions) {
+  /**
+   * @param {TemplateStrings | RenderOptions | string | undefined} strings
+   * @param {...HtmlSubstitution} substitutions
+   */
+  function tag (strings, ...substitutions) {
     if (!isTemplateStrings(strings)) {
       return createBoundTag(normalizeOptions(/** @type {RenderOptions | string | undefined} */ strings))
     }
@@ -68,17 +72,19 @@ function createBoundTag (options) {
       options,
       renderResult
     )
-  })
+  }
-  tag.fragment = fragment
-  tag.raw = raw
+  const htmlTag = /** @type {HtmlTag} */ (tag)
-  return tag
+  htmlTag.fragment = fragment
+  htmlTag.raw = raw
+  return htmlTag
 }
 /** @type {HtmlTag} */
 export const html = createBoundTag({})
 /**
- * @typedef {((strings: TemplateStringsArray | readonly string[], ...substitutions: unknown[]) => HtmlResult) & ((options?: RenderOptions | string) => HtmlTag) & { fragment: FragmentHelpers, raw: (value: unknown) => RawHtml }} HtmlTag
+ * @typedef {((strings: TemplateStrings, ...substitutions: HtmlSubstitution[]) => HtmlResult) & ((options?: RenderOptions | string) => HtmlTag) & { fragment: FragmentHelpers, raw: (value: unknown) => RawHtml }} HtmlTag
  */

package/lib/html-result.d.ts CHANGED Viewed

@@ -1,9 +1,9 @@
 export function isHtmlResult(value: unknown): value is HtmlResult;
 export const htmlResultSymbol: unique symbol;
 export class HtmlResult {
-    constructor(compiled: CompiledTemplate, substitutions: unknown[], options: RenderOptions, render: (result: HtmlResult) => string);
+    constructor(compiled: CompiledTemplate, substitutions: HtmlSubstitution[], options: RenderOptions, render: (result: HtmlResult) => string);
     compiled: CompiledTemplate;
-    substitutions: unknown[];
+    substitutions: HtmlSubstitution[];
     options: RenderOptions;
     render: (result: HtmlResult) => string;
     toString(): string;
@@ -12,5 +12,6 @@ export class HtmlResult {
     [htmlResultSymbol]: boolean;
 }
 import type { CompiledTemplate } from './create-tag.js';
+import type { HtmlSubstitution } from './html-types.js';
 import type { RenderOptions } from './create-tag.js';
 //# sourceMappingURL=html-result.d.ts.map

package/lib/html-result.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"html-result.d.ts","sourceRoot":"","sources":["html-result.js"],"names":[],"mappings":"~~AAoCA~~,oCAHW,OAAO,GACL,KAAK,IAAI,UAAU,CAQ/B;AAxCD,6CAA4D;AAE5D;IAOE,sBALW,gBAAgB,iBAChB,~~OAAO~~,EAAE,~~WACT~~,aAAa,UACb,CAAC,MAAM,EAAE,UAAU,KAAK,MAAM,EAQxC;IAJC,2BAAwB;IACxB,~~yBAAkC~~;IAClC,uBAAsB;IACtB,iBAPkB,UAAU,KAAK,MAAM,CAOnB;IAGtB,mBAEC;IAED,kBAEC;IAED,+BAEC;IAjBC,4BAA6B;CAkBhC;~~sCA9BoD~~,iBAAiB;~~mCAAjB~~,iBAAiB"}
1	+ {"version":3,"file":"html-result.d.ts","sourceRoot":"","sources":["html-result.js"],"names":[],"mappings":"AAqCA,oCAHW,OAAO,GACL,KAAK,IAAI,UAAU,CAQ/B;AAxCD,6CAA4D;AAE5D;IAOE,sBALW,gBAAgB,iBAChB,gBAAgB,EAAE,WAClB,aAAa,UACb,CAAC,MAAM,EAAE,UAAU,KAAK,MAAM,EAQxC;IAJC,2BAAwB;IACxB,kCAAkC;IAClC,uBAAsB;IACtB,iBAPkB,UAAU,KAAK,MAAM,CAOnB;IAGtB,mBAEC;IAED,kBAEC;IAED,+BAEC;IAjBC,4BAA6B;CAkBhC;sCA/BoD,iBAAiB;sCAChC,iBAAiB;mCADF,iBAAiB"}

package/lib/html-result.js CHANGED Viewed

@@ -1,11 +1,12 @@
 /** @import { CompiledTemplate, RenderOptions } from './create-tag.js' */
+/** @import { HtmlSubstitution } from './html-types.js' */
 export const htmlResultSymbol = Symbol('fragtml.htmlResult')
 export class HtmlResult {
   /**
    * @param {CompiledTemplate} compiled
-   * @param {unknown[]} substitutions
+   * @param {HtmlSubstitution[]} substitutions
    * @param {RenderOptions} options
    * @param {(result: HtmlResult) => string} render
    */

package/lib/html-types.d.ts ADDED Viewed

@@ -0,0 +1,9 @@
+import type { FragmentBoundary } from './fragment.js';
+import type { HtmlResult } from './html-result.js';
+import type { RawHtml } from './raw.js';
+export type HtmlPrimitiveSubstitution = string | number | bigint | boolean | null | undefined;
+export type HtmlArrayScalarSubstitution = HtmlPrimitiveSubstitution | HtmlResult | RawHtml;
+export type HtmlArraySubstitution = HtmlArrayScalarSubstitution | readonly HtmlArraySubstitution[];
+export type HtmlSubstitution = HtmlArraySubstitution | FragmentBoundary;
+export type TemplateStrings = TemplateStringsArray | readonly string[];
+//# sourceMappingURL=html-types.d.ts.map

package/lib/html-types.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"html-types.d.ts","sourceRoot":"","sources":["html-types.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAClD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AAEvC,MAAM,MAAM,yBAAyB,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAA;AAC7F,MAAM,MAAM,2BAA2B,GAAG,yBAAyB,GAAG,UAAU,GAAG,OAAO,CAAA;AAC1F,MAAM,MAAM,qBAAqB,GAAG,2BAA2B,GAAG,SAAS,qBAAqB,EAAE,CAAA;AAClG,MAAM,MAAM,gBAAgB,GAAG,qBAAqB,GAAG,gBAAgB,CAAA;AACvE,MAAM,MAAM,eAAe,GAAG,oBAAoB,GAAG,SAAS,MAAM,EAAE,CAAA"}

package/lib/html-types.ts ADDED Viewed

@@ -0,0 +1,10 @@
+// Type exports only. Do not add runtime implementations to this module.
+import type { FragmentBoundary } from './fragment.js'
+import type { HtmlResult } from './html-result.js'
+import type { RawHtml } from './raw.js'
+export type HtmlPrimitiveSubstitution = string | number | bigint | boolean | null | undefined
+export type HtmlArrayScalarSubstitution = HtmlPrimitiveSubstitution | HtmlResult | RawHtml
+export type HtmlArraySubstitution = HtmlArrayScalarSubstitution | readonly HtmlArraySubstitution[]
+export type HtmlSubstitution = HtmlArraySubstitution | FragmentBoundary
+export type TemplateStrings = TemplateStringsArray | readonly string[]

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "fragtml",
   "description": "WIP - nothing to see here",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "author": "Bret Comnes <bcomnes@gmail.com> (https://bret.io)",
   "bugs": {
     "url": "https://github.com/bcomnes/fragtml/issues"
@@ -48,7 +48,7 @@
     "build:declaration": "tsc -p declaration.tsconfig.json",
     "clean": "run-p clean:*",
     "clean:declarations-top": "rm -rf $(find . -maxdepth 1 -type f -name '*.d.ts*')",
-    "clean:declarations-lib": "rm -rf $(find lib -type f -name '*.d.ts*' ! -name '*-types.d.ts')"
+    "clean:declarations-lib": "rm -rf $(find lib -type f -name '*.d.ts*')"
   },
   "funding": {
     "type": "individual",