@terminalfour/terminalfour-js 1.0.0-rc.1

package/docs/navigation/pagination.md

@@ -0,0 +1,80 @@
+# Pagination
+
+Fetch content from a branch or section and split it across pages with navigation links.
+
+[Terminalfour Documentation](https://docs.terminalfour.com/documentation/navigation/create-a-new-navigation-object/pagination-navigation-object/)
+
+## Create
+
+```typescript
+await t4.navigation.create({
+  type: 'pagination',
+  name: 'Article Pagination',
+  properties: {
+    contentTypeId: 67,
+    fetchMethod: 'branch',
+    section: 233,
+    numToRecurse: 3,
+    contentItemsPerPage: 10,
+    maxContentItems: 100,
+    maxLinksPerPage: 5,
+    altLayoutName: 'text/json',
+    searchHiddenSections: true,
+    beforeHtml: '<nav>',
+    afterHtml: '</nav>',
+    beforePaginationHtml: '<ul>',
+    afterPaginationHtml: '</ul>',
+    betweenPaginationHtml: ' | ',
+  },
+});
+```
+
+## Fetch method summary
+
+| `fetchMethod` | `section` | `level` | `numToRecurse` |
+|---|---|---|---|
+| `'current'` | The SDK sets it to `0`. | The SDK sets it to `0`. | The SDK sets it to `0`. |
+| `'current-branch'` | The SDK sets it to `0`. | The SDK sets it to `0`. | You can set it. |
+| `'branch'` | Required and validated. | The SDK sets it to `0`. | You can set it. |
+| `'branch-at-level'` | Required and validated. | You can set it. | You can set it. |
+| `'section'` | Required and validated. | The SDK sets it to `0`. | The SDK sets it to `0`. |
+
+## Properties
+
+### Fetch scope
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `contentTypeId` | `number` | *required* | Content Type ID to paginate. |
+| `fetchMethod` | `string` | `'current'` | Fetch scope: `'current'`, `'current-branch'`, `'branch'`, `'branch-at-level'`, or `'section'`. |
+| `section` | `number` | `n/a` | Section ID for `'branch'`, `'branch-at-level'`, or `'section'`. |
+| `level` | `number` | `0` | Level for `'branch-at-level'`. |
+| `numToRecurse` | `number` | `0` | Recursion depth for `'current-branch'`, `'branch'`, or `'branch-at-level'`. |
+| `searchHiddenSections` | `boolean` | `false` | Includes hidden sections in the search. |
+
+### Pagination and layout
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `contentItemsPerPage` | `number` | `0` | Items per page. `0` disables pagination. |
+| `maxContentItems` | `number` | `0` | Maximum total items. `0` sets no limit. |
+| `maxLinksPerPage` | `number` | `0` | Maximum pagination links. `0` shows all links. |
+| `altLayoutName` | `string` | `''` | Alternative content layout name. |
+
+### Output HTML
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `beforeHtml` | `string` | `''` | HTML before content. |
+| `afterHtml` | `string` | `''` | HTML after content. |
+| `beforePaginationHtml` | `string` | `''` | HTML before pagination links. |
+| `afterPaginationHtml` | `string` | `''` | HTML after pagination links. |
+| `betweenPaginationHtml` | `string` | `''` | HTML between pagination links. |
+
+## Validation
+
+- `contentTypeId` is required and validated.
+- When provided, `altLayoutName` is validated against the content type's layouts.
+- The SDK validates `section` when the selected fetch method requires it.
+
+[Back to Navigation](../navigation.md)

package/docs/navigation/previous-next-fulltext.md

@@ -0,0 +1,43 @@
+# Previous/Next Fulltext Content
+
+Link sequential fulltext content items within a section.
+
+[Terminalfour Documentation](https://docs.terminalfour.com/documentation/navigation/create-a-new-navigation-object/previousnext-fulltext-content-navigation-object/)
+
+## Create
+
+```typescript
+await t4.navigation.create({
+  type: 'previous-next-fulltext',
+  name: 'Article Nav',
+  properties: {
+    type: 'both',
+    altLayoutName: 'text/nav',
+    skipNonFulltextContent: true,
+    onlyLinkToContentWithNav: false,
+    sameContentTypeRestriction: true,
+    displayOnBoundary: false,
+    displayContentNameAsTitle: true,
+    previousHtml: '« Previous',
+    betweenHtml: ' | ',
+    nextHtml: 'Next »',
+  },
+});
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `type` | `string` | `'previous'` | Link direction: `'previous'`, `'next'`, or `'both'`. |
+| `altLayoutName` | `string` | `''` | Alternative content layout name. |
+| `skipNonFulltextContent` | `boolean` | `false` | Skips content without fulltext. |
+| `onlyLinkToContentWithNav` | `boolean` | `false` | Links only to content that also has previous/next navigation. |
+| `sameContentTypeRestriction` | `boolean` | `false` | Restricts links to the same content type. |
+| `displayOnBoundary` | `boolean` | `false` | Displays links at the first and last boundaries. |
+| `displayContentNameAsTitle` | `boolean` | `false` | Uses the content name as the link title. |
+| `previousHtml` | `string` | `''` | HTML for the previous link. |
+| `betweenHtml` | `string` | `''` | HTML between links. |
+| `nextHtml` | `string` | `''` | HTML for the next link. |
+
+[Back to Navigation](../navigation.md)

package/docs/navigation/publish-to-one-file.md

@@ -0,0 +1,93 @@
+# Publish to One File
+
+Draw all content below a section, including content from child sections, into one page.
+
+[Terminalfour Documentation](https://docs.terminalfour.com/documentation/navigation/create-a-new-navigation-object/publish-to-one-file-navigation-object/)
+
+## Create
+
+```typescript
+await t4.navigation.create({
+  type: 'publish-to-one-file',
+  name: 'All Content',
+  properties: {
+    contentTypeId: 38,
+    startSection: 'specific',
+    section: 7725,
+    showHiddenSections: true,
+    levelsToRecurse: 10,
+    beforeHtml: '<div>',
+    afterHtml: '</div>',
+    showSectionName: true,
+    showNameForHidden: true,
+    beforeSectionName: '<h3>',
+    afterSectionName: '</h3>',
+    surroundingPageLayout: 344,
+    altLayoutName: 'text/foo',
+    enableCaching: true,
+    pagination: true,
+    contentPerPage: 10,
+    beforePaginationHtml: '<div class="pagination">',
+    betweenPaginationHtml: '|',
+    afterPaginationHtml: '</div>',
+  },
+});
+```
+
+## Properties
+
+### Common properties
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `contentTypeId` | `number \| null` | `null` | Content Type ID. `null` includes all content types. |
+| `startSection` | `string` | `'current'` | Content source: `'current'`, `'specific'`, or `'element'`. |
+| `showHiddenSections` | `boolean` | `false` | Includes hidden sections. |
+| `levelsToRecurse` | `number` | `1` | Number of levels to recurse. |
+| `beforeHtml` | `string` | `''` | HTML before content. |
+| `afterHtml` | `string` | `''` | HTML after content. |
+| `showSectionName` | `boolean` | `false` | Displays section names in the output. |
+| `surroundingPageLayout` | `number` | `n/a` | Page Layout ID. |
+| `altLayoutName` | `string` | `''` | Alternative content layout name. |
+| `enableCaching` | `boolean` | `true` | Controls output caching. |
+| `pagination` | `boolean` | `false` | Splits output across pages. |
+
+### When `startSection` is `'specific'`
+
+| Property | Type | Description |
+|---|---|---|
+| `section` | `number` | Required section ID. |
+
+### When `startSection` is `'element'`
+
+| Property | Type | Description |
+|---|---|---|
+| `startSectionElement` | `string` | Free-text content element name from which to derive the section. |
+
+### When `showSectionName` is `true`
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `showNameForHidden` | `boolean` | `false` | Shows names for hidden sections. |
+| `beforeSectionName` | `string` | `''` | HTML before each section name. |
+| `afterSectionName` | `string` | `''` | HTML after each section name. |
+
+### When `pagination` is `true`
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `contentPerPage` | `number` | `0` | Items per page. |
+| `beforePaginationHtml` | `string` | `''` | HTML before pagination. |
+| `betweenPaginationHtml` | `string` | `''` | HTML between pagination links. |
+| `afterPaginationHtml` | `string` | `''` | HTML after pagination. |
+
+## Validation
+
+- When `startSection` is `'specific'`, `section` is required and validated. Do not set it for other start-section modes.
+- Set `startSectionElement` only when `startSection` is `'element'`.
+- Set `showNameForHidden`, `beforeSectionName`, and `afterSectionName` only when `showSectionName` is `true`.
+- Set `contentPerPage` and the pagination HTML fields only when `pagination` is `true`.
+- The SDK validates `surroundingPageLayout` against page layouts.
+- The SDK validates `contentTypeId` when it is not `null`.
+
+[Back to Navigation](../navigation.md)

package/docs/navigation/related-content.md

@@ -0,0 +1,79 @@
+# Related Content
+
+Fetch and display content from the current section, a specific section, or a named child section.
+
+[Terminalfour Documentation](https://docs.terminalfour.com/documentation/navigation/create-a-new-navigation-object/related-content-navigation-object/)
+
+## Create
+
+```typescript
+// Current section
+await t4.navigation.create({
+  type: 'related-content',
+  name: 'Related',
+  properties: { fetchMethod: 'current', title: 'Related Items' },
+});
+
+// Specific section
+await t4.navigation.create({
+  type: 'related-content',
+  name: 'Related',
+  properties: {
+    fetchMethod: 'section',
+    section: 235,
+    altLayoutName: 'text/foo',
+  },
+});
+
+// Child section
+await t4.navigation.create({
+  type: 'related-content',
+  name: 'Related',
+  properties: {
+    fetchMethod: 'child',
+    childSectionName: 'Related Child',
+    contentTypeIds: [67, 363],
+    display: 5,
+    recurseChildSection: true,
+    altLayoutName: 'text/foo',
+  },
+});
+```
+
+## Properties
+
+### Common properties
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `fetchMethod` | `string` | `'current'` | Content source: `'current'`, `'section'`, or `'child'`. |
+| `title` | `string` | `''` | Title text. |
+| `altLayoutName` | `string` | `''` | Alternative content layout name. |
+| `beforeHtml` | `string` | `''` | HTML before content. |
+| `afterHtml` | `string` | `''` | HTML after content. |
+
+### When `fetchMethod` is `'section'`
+
+| Property | Type | Description |
+|---|---|---|
+| `section` | `number` | Required section ID. |
+
+### When `fetchMethod` is `'child'`
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `childSectionName` | `string` | `''` | Child section name to search. |
+| `contentTypeIds` | `number[]` | *required* | Content Type IDs by which to filter. |
+| `display` | `number` | `0` | Number of items. `0` displays all items. |
+| `recurseChildSection` | `boolean` | `false` | Searches recursively through child sections. |
+
+## Validation
+
+- When `fetchMethod` is `'section'`, `section` is required and validated.
+- When `fetchMethod` is `'child'`, `contentTypeIds` is required and validated.
+
+## Caching
+
+Caching is enabled by default.
+
+[Back to Navigation](../navigation.md)

package/docs/navigation/related-section-branch.md

@@ -0,0 +1,31 @@
+# Related Section Branch
+
+Link to a named child section across branches.
+
+[Terminalfour Documentation](https://docs.terminalfour.com/documentation/navigation/create-a-new-navigation-object/related-section-branch-navigation-object/)
+
+## Create
+
+```typescript
+await t4.navigation.create({
+  type: 'related-section-branch',
+  name: 'News Link',
+  properties: {
+    childSectionName: 'news',
+    linkText: 'View News',
+  },
+});
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `childSectionName` | `string` | `''` | Name of the child section to link to. |
+| `linkText` | `string` | `''` | Displayed link text. |
+
+## Validation
+
+No validation applies. Both fields are optional free-text strings.
+
+[Back to Navigation](../navigation.md)

package/docs/navigation/return-to-index.md

@@ -0,0 +1,35 @@
+# Return to Index
+
+Link from a fulltext content page back to its section index.
+
+[Terminalfour Documentation](https://docs.terminalfour.com/documentation/navigation/create-a-new-navigation-object/return-to-index-navigation-object/)
+
+## Create
+
+```typescript
+await t4.navigation.create({
+  type: 'return-to-index',
+  name: 'Back Link',
+  properties: {
+    linkText: 'Back to...',
+    appendSectionName: true,
+    scrollToContent: true,
+    linkTarget: '_blank',
+  },
+});
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `linkText` | `string` | `''` | Link text. |
+| `appendSectionName` | `boolean` | `false` | Appends the section name to the link text. |
+| `scrollToContent` | `boolean` | `false` | Scrolls to the content when clicked. |
+| `linkTarget` | `string` | `''` | Link target attribute, such as `'_blank'`. |
+
+## Validation
+
+All fields are optional.
+
+[Back to Navigation](../navigation.md)

package/docs/navigation/section-details.md

@@ -0,0 +1,51 @@
+# Section Details
+
+Output a section's ID, name, path, or link.
+
+[Terminalfour Documentation](https://docs.terminalfour.com/documentation/navigation/create-a-new-navigation-object/section-details-navigation-object/)
+
+## Create
+
+```typescript
+await t4.navigation.create({
+  type: 'section-details',
+  name: 'Show Section Path',
+  properties: {
+    detailMethod: 'section',
+    section: 233,
+    displayType: 'path',
+  },
+});
+```
+
+## Properties
+
+### Common properties
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `detailMethod` | `string` | `'current'` | Section selector: `'current'`, `'level'`, or `'section'`. |
+| `displayType` | `string` | `'id'` | Output value: `'id'`, `'name'`, `'path'`, or `'link'`. |
+
+### When `detailMethod` is `'level'`
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `level` | `number` | `0` | Section level. |
+
+### When `detailMethod` is `'section'`
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `section` | `number` | `n/a` | Required section ID. |
+
+## Validation
+
+- Set `level` only when `detailMethod` is `'level'`.
+- When `detailMethod` is `'section'`, `section` is required and validated. Do not set it for other methods.
+
+## Read behavior
+
+The SDK hides fields that do not apply to the current method.
+
+[Back to Navigation](../navigation.md)

package/docs/navigation/section-iterator.md

@@ -0,0 +1,33 @@
+# Section Iterator
+
+Iterate over sections to output content from multiple sections, with configurable HTML around and between them.
+
+[Terminalfour Documentation](https://docs.terminalfour.com/documentation/navigation/create-a-new-navigation-object/section-iterator-navigation-object/)
+
+## Create
+
+```typescript
+await t4.navigation.create({
+  type: 'section-iterator',
+  name: 'My Iterator',
+  properties: {
+    beforeHtml: '<ul>',
+    betweenHtml: '<li>',
+    afterHtml: '</ul>',
+  },
+});
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `beforeHtml` | `string` | `''` | HTML before the output. |
+| `betweenHtml` | `string` | `''` | HTML between sections. |
+| `afterHtml` | `string` | `''` | HTML after the output. |
+
+## Validation
+
+No validation applies. All fields are optional strings.
+
+[Back to Navigation](../navigation.md)

package/docs/navigation/section-meta-info.md

@@ -0,0 +1,39 @@
+# Section Meta Info
+
+Output the value of one section metadata tag.
+
+[Terminalfour Documentation](https://docs.terminalfour.com/documentation/navigation/create-a-new-navigation-object/section-meta-info-navigation-object/)
+
+## Create
+
+```typescript
+await t4.navigation.create({
+  type: 'section-meta-info',
+  name: 'OG Description',
+  properties: {
+    metaType: 'og:description',
+    dateFormat: 'dd.MM.yyyy',
+    beforeHtml: '<meta content="',
+    afterHtml: '">',
+  },
+});
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `metaType` | `string` | *required* | Meta tag name, such as `'description'` or `'og:title'`. |
+| `dateFormat` | `string` | `''` | Date format string, such as `'dd.MM.yyyy'`. |
+| `beforeHtml` | `string` | `''` | HTML before the output. |
+| `afterHtml` | `string` | `''` | HTML after the output. |
+
+## Validation
+
+`metaType` is required and validated against the meta tag definitions from `GET /meta/level`.
+
+## Read behavior
+
+The SDK resolves the numeric ID back to the metadata tag name.
+
+[Back to Navigation](../navigation.md)

package/docs/navigation/site-map.md

@@ -0,0 +1,58 @@
+# Site Map
+
+Output a hierarchical site map with optional content counts.
+
+[Terminalfour Documentation](https://docs.terminalfour.com/documentation/navigation/create-a-new-navigation-object/site-map-navigation-object/)
+
+## Create
+
+```typescript
+await t4.navigation.create({
+  type: 'site-map',
+  name: 'Full Site Map',
+  properties: {
+    startSection: 233,
+    levels: 5,
+    childSectionLinks: true,
+    enableContentCount: true,
+    contentTypeIds: [67, 363],
+    maxLevelsToCount: 10,
+    countRecursively: true,
+    htmlBeforeContentCount: '(',
+    htmlAfterContentCount: ')',
+  },
+});
+```
+
+## Properties
+
+### Common properties
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `startSection` | `number` | `0` | Starting section ID. `0` starts at the channel root. |
+| `levels` | `number` | `0` | Number of levels. `0` includes all levels. |
+| `childSectionLinks` | `boolean` | `false` | Shows links to child sections. |
+| `enableContentCount` | `boolean` | `false` | Adds content counts. |
+
+### When `enableContentCount` is `true`
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `contentTypeIds` | `number[]` | `[]` | Content Type IDs to count. An empty array includes all content types. |
+| `maxLevelsToCount` | `number` | `''` | Maximum levels to recurse while counting. |
+| `countRecursively` | `boolean` | `false` | Counts recursively through child sections. |
+| `htmlBeforeContentCount` | `string` | `''` | HTML before the count. |
+| `htmlAfterContentCount` | `string` | `''` | HTML after the count. |
+
+## Validation
+
+- The SDK validates `startSection` when it is a positive number.
+- The SDK validates every ID in `contentTypeIds` and requires each content type to exist.
+- Content-count fields throw when set without `enableContentCount: true`.
+
+## Read behavior
+
+The SDK hides content-count fields when `enableContentCount` is `false`.
+
+[Back to Navigation](../navigation.md)

package/docs/navigation/top-content.md

@@ -0,0 +1,80 @@
+# Top Content
+
+Display recent or relevant content from a section or branch, ordered by date or name.
+
+[Terminalfour Documentation](https://docs.terminalfour.com/documentation/navigation/create-a-new-navigation-object/top-content-navigation-object/)
+
+## Create
+
+```typescript
+await t4.navigation.create({
+  type: 'top-content',
+  name: 'Latest Articles',
+  properties: {
+    fetchMethod: 'section',
+    section: 237,
+    contentTypeIds: [67, 151],
+    channelId: 5,
+    upcomingContent: true,
+    dateElement: 'Date released',
+    ignoreDateOrdering: false,
+    numToDisplay: 5,
+    startAt: 10,
+    altLayoutName: 'text/foo',
+    title: 'Latest',
+    beforeHtml: '<ul>',
+    afterHtml: '</ul>',
+  },
+});
+```
+
+## Properties
+
+### Common properties
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `fetchMethod` | `string` | `'current'` | Content source: `'current'`, `'current-branch'`, `'branch'`, or `'section'`. |
+| `contentTypeIds` | `number[]` | `[]` | Content Type IDs by which to filter. An empty array includes all content types. |
+| `channelId` | `number` | `0` | Channel ID. `0` applies no channel restriction. |
+
+### When `fetchMethod` is `'branch'` or `'section'`
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `section` | `number` | `n/a` | Required section ID. |
+
+### Ordering and filtering
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `upcomingContent` | `boolean` | `false` | Includes upcoming or future content. |
+| `dateElement` | `string` | `''` | Date element name for ordering and filtering. |
+| `ignoreDateOrdering` | `boolean` | `false` | Uses Terminalfour's section order instead of date order. |
+
+### Results and output
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `numToDisplay` | `number` | `0` | Number of items. `0` displays all items. |
+| `startAt` | `number` | `0` | Skips this many items from the start. |
+| `altLayoutName` | `string` | `''` | Alternative content layout name. |
+| `title` | `string` | `''` | Title text. |
+| `beforeHtml` | `string` | `''` | HTML before content. |
+| `afterHtml` | `string` | `''` | HTML after content. |
+
+## Validation
+
+- When `fetchMethod` is `'branch'` or `'section'`, `section` is required and validated. Do not set it for the other fetch methods.
+- The SDK validates each ID in `contentTypeIds` and requires every content type to exist.
+- The SDK validates `channelId` when it is a positive number.
+
+## Read behavior
+
+The SDK hides `section` when the fetch method does not use it.
+
+## Caching
+
+Caching is enabled by default.
+
+[Back to Navigation](../navigation.md)

package/docs/navigation/top-stories.md

@@ -0,0 +1,47 @@
+# Top Stories
+
+Display content from one section with optional links to fulltext pages.
+
+[Terminalfour Documentation](https://docs.terminalfour.com/documentation/navigation/create-a-new-navigation-object/top-stories-navigation-object/)
+
+## Create
+
+```typescript
+await t4.navigation.create({
+  type: 'top-stories',
+  name: 'Latest News',
+  properties: {
+    section: 237,
+    numToShow: 10,
+    linkToFulltext: true,
+    title: 'Latest',
+    beforeMenuHtml: '<ul>',
+    afterMenuHtml: '</ul>',
+    beforeHtml: '<li>',
+    afterHtml: '</li>',
+  },
+});
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `section` | `number` | *required* | Section ID. |
+| `numToShow` | `number` | `0` | Number of items. `0` displays all items. |
+| `linkToFulltext` | `boolean` | `false` | Links items to their fulltext pages. |
+| `title` | `string` | `''` | Title text. |
+| `beforeMenuHtml` | `string` | `''` | HTML before the menu. |
+| `afterMenuHtml` | `string` | `''` | HTML after the menu. |
+| `beforeHtml` | `string` | `''` | HTML before each item. |
+| `afterHtml` | `string` | `''` | HTML after each item. |
+
+## Validation
+
+`section` is required and validated.
+
+## Caching
+
+Caching is enabled by default.
+
+[Back to Navigation](../navigation.md)