@terminalfour/terminalfour-js 1.0.0-rc.1

package/docs/media.md

@@ -0,0 +1,169 @@
+# Media
+
+Use `t4.media` for files, `t4.mediaCategory(id)` for category operations, and `t4.mediaLibrary` for the complete category tree.
+
+## Contents
+
+- [Media items](#media-items)
+- [Create and update media](#create-and-update-media)
+- [Delete or purge media](#delete-or-purge-media)
+- [Media categories](#media-categories)
+- [Media library tree](#media-library-tree)
+
+## Media items
+
+### Get a media item
+
+```typescript
+const media = await t4.media.get(10928);
+```
+
+| Property | Example or meaning |
+|---|---|
+| `id` | `10928` |
+| `name` | `'Cat Photo'` |
+| `description` | `'A cat running through grass'` |
+| `fileName` | `'cat-image.jpg'` |
+| `fileSize` | `'28.7 KB'` |
+| `mediaType` | `'Image'` |
+| `mediaTypeId` | `1` |
+| `language` | `'smxx'` |
+| `version` | `'1.0'` |
+| `status` | `'approved'` |
+| `downloadUrl` | Download URL |
+| `thumbnailUrl` | Thumbnail URL |
+| `path` | `'Media Library » Images » Cats'` |
+| `categories` | Category IDs, such as `[366]` |
+| `fields` | Custom values, such as `{ 'Photo Credit': 'Jane Smith' }` |
+
+### Non-binary media
+
+CSS, JavaScript, PHP, and other non-binary media expose text content and a syntax type:
+
+```typescript
+const css = await t4.media.get(4635);
+console.log(css.content);    // '* { box-sizing: border-box; }'
+console.log(css.syntaxType); // 'css'
+
+css.content = '* { color: red; }';
+await css.save(); // increments the version
+```
+
+You can also replace a non-binary file. The save request includes both the file and text content:
+
+```typescript
+css.file = './new-styles.css';
+await css.save();
+```
+
+## Create and update media
+
+### Create media
+
+The SDK detects the media type from the file extension:
+
+```typescript
+const image = await t4.media.create({
+  file: './hero-image.jpg',
+  name: 'Hero Image',
+  category: 391,
+  description: 'Homepage hero',
+});
+
+const stylesheet = await t4.media.create({
+  file: { file: new Blob(['body { color: red; }']), filename: 'styles.css' },
+  name: 'Main Stylesheet',
+  category: 355,
+});
+```
+
+### Direct update
+
+```typescript
+await t4.media.update(10928, {
+  name: 'Renamed',
+  description: 'Updated',
+  file: './replacement.png', // optional replacement
+});
+```
+
+### Mutable item
+
+```typescript
+const media = await t4.media.get(10928);
+media.name = 'Updated Cat';
+media.description = 'A fast cat';
+media.fields['Photo Credit'] = 'New Photographer';
+await media.save();
+```
+
+Assign `file` to replace the current file. A save increments the version automatically:
+
+```typescript
+media.file = './new-image.png';
+await media.save();
+```
+
+`file` accepts a local path, HTTPS URL, Blob, or `{ file, filename }`. If the replacement has a different file type, such as replacing CSS with PNG, the SDK recalculates the media type and syntax type from the new extension.
+
+## Delete or purge media
+
+```typescript
+await t4.media.delete(10928); // selects the category when the media is in one category
+await t4.media.delete(10928, { categoryId: 366 }); // required for multiple categories
+await t4.media.purge(10928); // permanent removal; media must be deleted first
+```
+
+## Media categories
+
+`t4.mediaCategory(id)` creates a lightweight `MediaCategoryRef` without making an API request.
+
+### Read and update a category
+
+#### Direct update
+
+```typescript
+await t4.mediaCategory(367).update({ name: 'Renamed' });
+```
+
+#### Mutable item
+
+```typescript
+const category = await t4.mediaCategory(367).get();
+console.log(category.id, category.name, category.path, category.lastModified);
+
+category.name = 'Renamed';
+await category.save();
+```
+
+### List media and subcategories
+
+```typescript
+const items = await t4.mediaCategory(367).list();
+// [{ id, name, description, fileName, fileSize, mediaType, language, version, status, lastModified }]
+
+const subcategories = await t4.mediaCategory(366).subcategories();
+// [{ id, name, lastModified }]
+```
+
+### Create, delete, purge, or move a category
+
+```typescript
+const child = await t4.mediaCategory(367).addCategory({ name: 'New Folder' });
+
+await t4.mediaCategory(500).delete();
+await t4.mediaCategory(500).purge();
+await t4.mediaCategory(500).move(367); // move under category 367
+```
+
+## Media library tree
+
+```typescript
+const tree = await t4.mediaLibrary.tree();
+```
+
+The result is the full category hierarchy as `MediaCategoryNode` objects with `id`, `name`, and optional `children`.
+
+---
+
+**Previous:** [Page Layouts](./page-layouts.md) · **Next:** [Media Types](./media-types.md)

package/docs/navigation/a-to-z.md

@@ -0,0 +1,62 @@
+# A to Z Navigation
+
+Build an alphabetical section listing for a directory-style page.
+
+[Terminalfour Documentation](https://docs.terminalfour.com/documentation/navigation/create-a-new-navigation-object/a-to-z-navigation-object/)
+
+## Create
+
+```typescript
+await t4.navigation.create({
+  type: 'a-to-z',
+  name: 'Department A-Z',
+  properties: {
+    startLevel: 2,
+    endLevel: 5,
+    useSectionMetaData: true,
+    sectionMetaContentTypeElement: 'Title',
+    microSite: 6,
+    beforeMenu: '<ul class="az-nav">',
+    afterMenu: '</ul>',
+    beforeItem: '<li>',
+    afterItem: '</li>',
+  },
+});
+```
+
+## Properties
+
+### Common properties
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `startLevel` | `number` | `0` | Starts generation at this level. `0` starts at the root. |
+| `endLevel` | `number` | `0` | Stops generation at this level. `0` includes all sections. |
+| `useSectionMetaData` | `boolean` | `false` | Uses a Section Meta Data element instead of the section name. |
+| `microSite` | `number \| null` | `null` | Restricts the navigation to this microsite ID. |
+| `beforeMenu` | `string` | `''` | HTML before the menu. |
+| `afterMenu` | `string` | `''` | HTML after the menu. |
+| `beforeItem` | `string` | `''` | HTML before each item. |
+| `afterItem` | `string` | `''` | HTML after each item. |
+
+### When `useSectionMetaData` is `true`
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `sectionMetaContentTypeElement` | `string` | `''` | Names the element on the Section Meta Data content type. |
+
+## Validation
+
+- Set `sectionMetaContentTypeElement` only when `useSectionMetaData` is `true`.
+- The SDK validates `sectionMetaContentTypeElement` against the elements on the Section Meta Data content type.
+- The SDK validates `microSite` against the microsites configured on all channels.
+
+## API notes
+
+The SDK gets the Section Meta Data content type through `GET /config/hierarchy.metaDataContentType`.
+
+## Caching
+
+Caching is always disabled for this type.
+
+[Back to Navigation](../navigation.md)

package/docs/navigation/breadcrumbs.md

@@ -0,0 +1,67 @@
+# Breadcrumbs
+
+Show the current page's hierarchy and link back through its parent sections.
+
+[Terminalfour Documentation](https://docs.terminalfour.com/documentation/navigation/create-a-new-navigation-object/breadcrumbs-navigation-object/)
+
+## Create
+
+```typescript
+await t4.navigation.create({
+  type: 'breadcrumbs',
+  name: 'Main Breadcrumbs',
+  properties: {
+    startLevel: 1,
+    endLevel: 0,
+    useLinks: true,
+    linkCurrent: false,
+    hideHome: true,
+    noSpace: true,
+    maxLength: 50,
+    separator: ' > ',
+    elementToAppend: 'Title',
+    beforeHtml: '<nav aria-label="breadcrumb">',
+    afterHtml: '</nav>',
+  },
+});
+```
+
+## Properties
+
+### Level range
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `startLevel` | `number` | `0` | Starts at this level. `0` starts at the root. |
+| `endLevel` | `number` | `0` | Ends at this level. `0` includes all levels. |
+| `maxLength` | `number` | `0` | Truncates after this many characters. `0` sets no limit. |
+
+### Link behavior
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `useLinks` | `boolean` | `false` | Turns breadcrumb items into links. |
+| `linkCurrent` | `boolean` | `false` | Turns the current, last item into a link. |
+| `hideHome` | `boolean` | `false` | Hides the home section. |
+| `noSpace` | `boolean` | `false` | Removes spaces from links. |
+
+### Content and output
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `separator` | `string` | `''` | HTML between items. |
+| `elementToAppend` | `string` | `''` | Names the content element to append. |
+| `beforeHtml` | `string` | `''` | HTML before the breadcrumb. |
+| `afterHtml` | `string` | `''` | HTML after the breadcrumb. |
+
+## Validation
+
+- `startLevel`, `endLevel`, and `maxLength` must be zero or greater.
+- Set either a positive `startLevel` or `endLevel`, or a positive `maxLength`. Do not combine the level range with `maxLength`.
+- Set `noSpace` to `true` only when `useLinks` is `true`.
+
+## API behavior
+
+Setting `elementToAppend` automatically enables the append-content-element flag.
+
+[Back to Navigation](../navigation.md)

package/docs/navigation/css-selector.md

@@ -0,0 +1,53 @@
+# CSS Selector
+
+Apply different CSS stylesheets to different branches of the site hierarchy.
+
+[Terminalfour Documentation](https://docs.terminalfour.com/documentation/navigation/create-a-new-navigation-object/css-selector-navigation-object/)
+
+## Create
+
+```typescript
+await t4.navigation.create({
+  type: 'css-selector',
+  name: 'My CSS Selector',
+  properties: {
+    defaultStylesheet: 11299,
+    language: 'en',
+    branches: [
+      { stylesheet: 4767, rootSection: 233 },
+      { stylesheet: 4768, name: 'Homepage' },
+    ],
+  },
+});
+```
+
+## Properties
+
+### Common properties
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `defaultStylesheet` | `number` | *required* | Media ID of the default stylesheet. |
+| `language` | `string` | `''` | Language code. |
+| `branches` | `array` | `[]` | Branch-specific stylesheet overrides. |
+
+### Branch object
+
+| Property | Type | Description |
+|---|---|---|
+| `stylesheet` | `number` | Media ID of the stylesheet for this branch. Required. |
+| `name` | `string` | Section name to match. Do not combine it with `rootSection`. |
+| `rootSection` | `number` | Section ID to use as the root. Do not combine it with `name`. |
+
+## Validation
+
+- `defaultStylesheet` is required, and its media item must exist.
+- The SDK validates each branch `stylesheet`.
+- The SDK validates each branch `rootSection` and requires the section to exist.
+- A branch cannot contain both `name` and `rootSection`.
+
+## API notes
+
+The SDK sends branch properties only when `branches` is provided.
+
+[Back to Navigation](../navigation.md)

package/docs/navigation/generate-file.md

@@ -0,0 +1,48 @@
+# Generate File
+
+Publish a file from a content layout or media item into a directory during publishing.
+
+[Terminalfour Documentation](https://docs.terminalfour.com/documentation/navigation/create-a-new-navigation-object/generate-file--navigation-object/)
+
+## Create
+
+```typescript
+await t4.navigation.create({
+  type: 'generate-file',
+  name: 'RSS Feed Generator',
+  properties: {
+    fileName: 'feed',
+    fileExtension: 'xml',
+    layout: 'text/rss',
+    appendContentId: true,
+    appendDirectory: true,
+    baseDirectory: '/feeds',
+    mediaFile: 4767,
+  },
+});
+```
+
+## Properties
+
+### File and source
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `fileName` | `string` | `''` | Output file name. |
+| `fileExtension` | `string` | `''` | Generated file extension. |
+| `layout` | `string` | `''` | Content layout name. |
+| `mediaFile` | `number \| null` | `null` | Media ID to associate. |
+
+### Output path
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `appendContentId` | `boolean` | `false` | Appends the content ID to the file name. |
+| `appendDirectory` | `boolean` | `false` | Appends the directory path. |
+| `baseDirectory` | `string` | `''` | Base output directory. |
+
+## Validation
+
+When `mediaFile` is provided, the SDK validates it against the media library.
+
+[Back to Navigation](../navigation.md)

package/docs/navigation/keyword-search.md

@@ -0,0 +1,134 @@
+# Keyword Search Content
+
+Find and display content items that share keywords with the current content across sections.
+
+[Terminalfour Documentation](https://docs.terminalfour.com/documentation/navigation/create-a-new-navigation-object/keyword-search-content-navigation-object/)
+
+## Create
+
+```typescript
+await t4.navigation.create({
+  type: 'keyword-search',
+  name: 'Keywords Search',
+  properties: {
+    // Keyword Retrieval
+    keywordFetchMethod: 'section',
+    keywordSection: 233,
+    narrowToSingleContentItem: true,
+    keywordContentTypeId: 343,
+    keywordElements: ['Cascading List', 'Keyword Selector'],
+
+    // Content Retrieval
+    contentFetchMethod: 'section',
+    searchSection: 7805,
+    searchContentTypeId: 67,
+    searchElements: ['Finditems'],
+
+    // Display
+    numToDisplay: 10,
+    sortType: 'name',
+    sortByDateElement: true,
+    dateElementName: 'Release Date',
+    showHiddenSections: true,
+    matchCompositeKeywords: true,
+    matchSubItems: true,
+    crossLanguageSearch: true,
+    crossLanguageLanguages: ['en', 'es'],
+
+    // Output
+    altLayoutName: 'text/bar',
+    beforeHtml: '<div>',
+    afterHtml: '</div>',
+    pagination: true,
+    contentPerPage: 20,
+  },
+});
+```
+
+## Properties
+
+### Common properties
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `keywordFetchMethod` | `string` | `'current'` | Keyword source: `'current'`, `'parent'`, or `'section'`. |
+| `narrowToSingleContentItem` | `boolean` | `false` | Narrows the keyword source to one content item. |
+| `keywordContentTypeId` | `number \| null` | `null` | Content Type ID. `null` accepts any content type. |
+| `keywordElements` | `string[]` | `[]` | Element names from which to get keywords. |
+| `contentFetchMethod` | `string` | `'section'` | Content scope: `'section'`, `'branch'`, or `'branch-at-level'`. |
+| `searchContentTypeId` | `number \| null` | `null` | Content Type ID to search. `null` accepts any content type. |
+| `searchElements` | `string[]` | `[]` | Element names in which to search for keywords. |
+
+### When `keywordFetchMethod` is `'section'`
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `keywordSection` | `number` | `n/a` | Section ID from which to get keywords. |
+
+### When `contentFetchMethod` is `'section'` or `'branch'`
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `searchSection` | `number` | `n/a` | Section to search. Use this or `searchSectionElement`, not both. |
+| `searchSectionElement` | `string` | `n/a` | Element name from which to derive the section. Use this or `searchSection`, not both. |
+
+### When `contentFetchMethod` is `'branch-at-level'`
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `startLevel` | `number` | `0` | Starting level. |
+| `endLevel` | `number` | `0` | Ending level or recursion depth. |
+
+### Display
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `numToDisplay` | `number` | `0` | Number of items. `0` displays all items. |
+| `sortType` | `string` | `'name'` | Sort order: `'name'`, `'name-desc'`, or `'last-modified'`. |
+| `sortByDateElement` | `boolean` | `false` | Sorts by a date element. |
+| `showUpcomingContent` | `boolean` | `false` | Includes upcoming or future content. |
+| `showHiddenSections` | `boolean` | `false` | Includes hidden sections. |
+| `matchCompositeKeywords` | `boolean` | `false` | Matches composite keywords. |
+| `matchSubItems` | `boolean` | `false` | Matches sub-items. |
+| `crossLanguageSearch` | `boolean` | `false` | Searches across languages. |
+| `crossLanguageLanguages` | `string[]` | `[]` | Language codes, such as `['en', 'es']`. |
+
+### When `sortByDateElement` is `true`
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `dateElementName` | `string` | `n/a` | Date element name. |
+
+### Output
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `altLayoutName` | `string` | `''` | Alternative content layout name. |
+| `beforeHtml` | `string` | `''` | HTML before content. |
+| `afterHtml` | `string` | `''` | HTML after content. |
+| `pagination` | `boolean` | `false` | Paginates the results. |
+
+### 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 `keywordFetchMethod` is `'section'`, `keywordSection` is required and validated.
+- For a `'section'` or `'branch'` content search, set exactly one of `searchSection` and `searchSectionElement`.
+- The SDK validates `searchSectionElement` against content type elements when `keywordContentTypeId` is a positive number.
+- Provide `startLevel` and `endLevel` only for `'branch-at-level'`.
+- Provide `dateElementName` only when `sortByDateElement` is `true`.
+- Provide pagination fields only when `pagination` is `true`.
+- The SDK validates non-null `keywordContentTypeId` and `searchContentTypeId` values.
+
+## Caching
+
+Caching is enabled by default.
+
+[Back to Navigation](../navigation.md)

package/docs/navigation/language-switcher.md

@@ -0,0 +1,37 @@
+# Language Switcher
+
+Link between language versions of the current page on a multilingual site.
+
+[Terminalfour Documentation](https://docs.terminalfour.com/documentation/navigation/create-a-new-navigation-object/language-switcher-navigation-object/)
+
+## Create
+
+```typescript
+await t4.navigation.create({
+  type: 'language-switcher',
+  name: 'Language Nav',
+  properties: {
+    langCode: 'en',
+    alwaysOutput: true,
+    imageUrl: 'https://example.com/flags',
+    imageExtension: '.gif',
+    imageProperties: 'width="30" height="30"',
+    beforeHtml: '<div class="langs">',
+    afterHtml: '</div>',
+  },
+});
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `langCode` | `string` | `''` | Language code. |
+| `alwaysOutput` | `boolean` | `false` | Outputs the switcher when only one language exists. |
+| `imageUrl` | `string` | `''` | URL for image-based language links. |
+| `imageExtension` | `string` | `''` | File extension for language images, such as `.gif`. |
+| `imageProperties` | `string` | `''` | HTML image attributes, such as `width="30"`. |
+| `beforeHtml` | `string` | `''` | HTML before the switcher. |
+| `afterHtml` | `string` | `''` | HTML after the switcher. |
+
+[Back to Navigation](../navigation.md)

package/docs/navigation/link-menu.md

@@ -0,0 +1,105 @@
+# Link Menu
+
+Build section links for main navigation menus or sidebars.
+
+[Terminalfour Documentation](https://docs.terminalfour.com/documentation/navigation/create-a-new-navigation-object/link-menu-navigation-object/)
+
+## Create
+
+```typescript
+// Branch at level
+await t4.navigation.create({
+  type: 'link-menu',
+  name: 'Main Nav',
+  properties: {
+    menuType: 'branch-at-level',
+    level: 2,
+    numToRecurse: 3,
+    subNavigationType: 'ul',
+    menuDisplayType: 'normal',
+    showNonCurrentChildren: true,
+    useCurrentBranchClass: true,
+    currentSectionLink: true,
+    addSectionName: true,
+    title: 'Navigation',
+    beforeMenuHtml: '<ul>',
+    afterMenuHtml: '</ul>',
+    beforeLinkHtml: '<li>',
+    afterLinkHtml: '</li>',
+    betweenLink: '',
+  },
+});
+
+// Children with specific branch
+await t4.navigation.create({
+  type: 'link-menu',
+  name: 'Child Nav',
+  properties: {
+    menuType: 'children',
+    displaySpecificBranch: true,
+    specificBranchId: 233,
+    showSiblingsIfNoChildren: true,
+    showAncestorsIfNoChildren: false,
+  },
+});
+```
+
+## Menu type summary
+
+| `menuType` | Mode-specific properties |
+|---|---|
+| `'branch-at-level'` | `level` and `numToRecurse` |
+| `'children'` | `displaySpecificBranch`, `specificBranchId`, `showSiblingsIfNoChildren`, `showAncestorsIfNoChildren` |
+| `'siblings'` | `n/a` |
+| `'siblings-and-children'` | `subNavigationType` |
+
+## Properties
+
+### Common properties
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `menuType` | `string` | *required* | Menu scope: `'branch-at-level'`, `'children'`, `'siblings'`, or `'siblings-and-children'`. |
+| `menuDisplayType` | `string` | `'normal'` | Display type: `'normal'` or `'dropdown'`. |
+| `showNonCurrentChildren` | `boolean` | `false` | Shows children of non-current sections. |
+| `useCurrentBranchClass` | `boolean` | `false` | Adds a CSS class to the current branch. |
+| `currentSectionLink` | `boolean` | `false` | Turns the current section into a link. |
+| `addSectionName` | `boolean` | `false` | Prepends the section name to the title. |
+| `title` | `string` | `''` | Title text. |
+| `beforeMenuHtml` | `string` | `''` | HTML before the menu. |
+| `afterMenuHtml` | `string` | `''` | HTML after the menu. |
+| `beforeLinkHtml` | `string` | `''` | HTML before each link. |
+| `afterLinkHtml` | `string` | `''` | HTML after each link. |
+| `betweenLink` | `string` | `''` | HTML between links. |
+
+### When `menuType` is `'branch-at-level'`
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `level` | `number` | `0` | Starting level. |
+| `numToRecurse` | `number` | `1` | Recursion depth. |
+| `subNavigationType` | `string` | `'ul'` | Nested navigation type: `'ul'`, `'table'`, or `'div'`. |
+
+### When `menuType` is `'children'`
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `displaySpecificBranch` | `boolean` | `false` | Displays a specific branch. |
+| `specificBranchId` | `number` | `n/a` | Section ID of the specific branch. |
+| `showSiblingsIfNoChildren` | `boolean` | `false` | Shows siblings when no children exist. |
+| `showAncestorsIfNoChildren` | `boolean` | `false` | Shows ancestors when no children exist. |
+
+### When `menuType` is `'siblings-and-children'`
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `subNavigationType` | `string` | `'ul'` | Nested navigation type: `'ul'`, `'table'`, or `'div'`. |
+
+## Validation
+
+- Set `level` and `numToRecurse` only for `'branch-at-level'`.
+- Set `subNavigationType` for `'branch-at-level'` only when `numToRecurse` is greater than 1. You can also set it for `'siblings-and-children'`.
+- Set `displaySpecificBranch`, `showSiblingsIfNoChildren`, and `showAncestorsIfNoChildren` only for `'children'`.
+- Set `specificBranchId` only when `displaySpecificBranch` is `true`. The SDK validates the section ID.
+
+[Back to Navigation](../navigation.md)