{"id":17025457,"url":"https://github.com/jackyzha0/telescopic-text","last_synced_at":"2025-05-08T17:11:06.894Z","repository":{"id":39534100,"uuid":"457989319","full_name":"jackyzha0/telescopic-text","owner":"jackyzha0","description":"🔭 an open-source library to help with creating expandable text","archived":false,"fork":false,"pushed_at":"2023-07-05T06:51:31.000Z","size":2466,"stargazers_count":89,"open_issues_count":6,"forks_count":3,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-05-08T17:03:44.849Z","etag":null,"topics":["interaction-design","telescopic-text"],"latest_commit_sha":null,"homepage":"https://jackyzha0.github.io/telescopic-text/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jackyzha0.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-02-11T00:09:52.000Z","updated_at":"2025-03-06T08:59:32.000Z","dependencies_parsed_at":"2024-10-26T21:21:55.360Z","dependency_job_id":"cc85104a-11c5-4314-a368-8bc774fc808e","html_url":"https://github.com/jackyzha0/telescopic-text","commit_stats":{"total_commits":76,"total_committers":4,"mean_commits":19.0,"dds":0.381578947368421,"last_synced_commit":"dd718555fdca9076b93405146b297fcda55eb08f"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jackyzha0%2Ftelescopic-text","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jackyzha0%2Ftelescopic-text/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jackyzha0%2Ftelescopic-text/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jackyzha0%2Ftelescopic-text/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jackyzha0","download_url":"https://codeload.github.com/jackyzha0/telescopic-text/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253112073,"owners_count":21856070,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["interaction-design","telescopic-text"],"created_at":"2024-10-14T07:29:13.002Z","updated_at":"2025-05-08T17:11:04.002Z","avatar_url":"https://github.com/jackyzha0.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🔭 Telescopic Text\n\n[![](https://img.shields.io/npm/v/telescopic-text?style=flat-square)](https://www.npmjs.com/package/telescopic-text)\n\nAn open-source library to help with creating expandable text.\n\nInspired by [StretchText](https://en.wikipedia.org/wiki/StretchText) and [TelescopicText](https://www.telescopictext.org/text/KPx0nlXlKTciC).\n\n# Background\n\nI've been thinking a lot about creating a browsable store of knowledge that provides something useful at all distance scales\n(e.g. viewing the entire library, just a subcategory, a single file, etc.) and concepts like Telescopic Text are a first step\nin creating more information scales than just a single document level.\n\nThis library is meant to be the start for anyone to create telescopic text, including those who are non-technical.\n\n## Creating a telescopic text\n\nTo create some telescopic text, you can use your favorite note-taking app or text editor that supports bullet lists and start by writing a full sentence or two in a starting bullet:\n\nHead to https://poems.verses.xyz/test to use an interactive playground for writing in bullet lists and get the corresponding code that leverages this library to generate the interactive text for use on your own website.\n\n_NOTE_: the parsing logic is robust to different indentation levels, but for most compatible experience, you should normalize the indentations so that each nested bullet is differentiated by a standard set of spaces. We also currently only support `*`, `-`, and `+` bullet indicators.\n\n## Usage\n\nCreate some expandable text using the bullet list format shown above. You can then test out how your poem looks and feels and get a basic code snippet that recreates it using the [test bed](https://poems.verses.xyz/test)!\n\nSee the full instructions below:\n\nYou can load it directly via CDN as follows:\nPut this anywhere inside the `head` of your HTML file.\n\n```html\n\u003chead\u003e\n  ...\n  \u003cscript src=\"https://unpkg.com/telescopic-text/lib/index.js\"\u003e\u003c/script\u003e\n  \u003clink\n    href=\"https://unpkg.com/telescopic-text/lib/index.css\"\n    rel=\"stylesheet\"\n  /\u003e\n\u003c/head\u003e\n```\n\nor if you prefer to do the manual way, you can include the `lib/index.js` and `lib/index.css` files in your project.\n\nThe package exports a function called `createTelescopicTextFromBulletedList` that parses a bulleted list and returns a HTMLNode with your telescopic text inside.\n\nBasic usage may look something like this:\n\n```html\n\u003chead\u003e\n  \u003cscript src=\"https://unpkg.com/telescopic-text/lib/index.js\"\u003e\u003c/script\u003e\n  \u003clink\n    href=\"https://unpkg.com/telescopic-text/lib/index.css\"\n    rel=\"stylesheet\"\n  /\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n  \u003cdiv id=\"text-container\"\u003e\u003c/div\u003e\n\n  \u003cscript\u003e\n    const content = `\n  * I \n    * Yawning, I\n  * made tea`;\n    const node = createTelescopicTextFromBulletedList(content);\n    const container = document.getElementById(\"text-container\");\n    container.appendChild(node);\n  \u003c/script\u003e\n\u003c/body\u003e\n```\n\n### Advanced Usage Options\n\nFor further, customization, we provide a configuration object that can be passed into the function for different behavior.\n\n```typescript\n// The configuration for how you want telescopic text to be parsed and rendered\ninterface Config {\n  /**\n   * Character used to separate entries on the same level. Defaults to a single space (\" \")\n   */\n  separator?: string;\n  /**\n   * If true, allows sections to expand automatically on mouse over rather than requiring a click. Defaults to false.\n   */\n  shouldExpandOnMouseOver?: boolean;\n  /**\n   * A mode that designates what form the input text is in and should be interpreted as. Defaults to 'text'.\n   */\n  textMode?: TextMode;\n  /**\n   * Determines the wrapper element type for HTML elements. Defaults to 'span'.\n   */\n  htmlContainerTag?: keyof HTMLElementTagNameMap;\n  /**\n   * Only valid when textMode is 'text'. Used to insert HTML element like blockquotes, line breaks, bold, and emphasis in plain text mode.\n   */\n  specialCharacters?: TextReplacements;\n}\n```\n\nYou would use this by passing a custom configuration object into the function in order to override any of the defaults above. For example, this is how you would create telescopic text with custom HTML tags:\n\n```javascript\nconst content = `\n* Some \u003cb\u003erich\u003c/b\u003e text\n  * with \u003ci\u003enested\u003c/i\u003e \u003cb\u003erich\u003c/b\u003e text\n`;\nconst config = { textMode: TextMode.Html };\nconst poemContent = createTelescopicTextFromBulletedList(content, config);\n```\n\nYou can check out a more detailed example in `demo/index.html`\n\nIf you are using plain 'text' as the textMode, you can also define an object containing special characters and the rules for how to replace them.\n\n```typescript\ninterface TextReplacements {\n  // Each entry is keyed by its regex string match\n  // It defines a function that takes in the current line of text as well as its parent node\n  // and\n  [key: string]: (lineText: string) =\u003e HTMLElement\n}\n\n// for example, here's a text replacement rule for bolding text that is wrapped with *\n\"\\\\*(.*)\\\\*\": (lineText) =\u003e {\n  const el = document.createElement(\"strong\");\n  el.appendChild(document.createTextNode(lineText));\n  return el;\n}\n```\n\nBy default, only these special characters have text replacements\n\n- line breaks (`---`)\n- bold (`*...*`)\n- emphasis (`_..._`)\n  To disable this, you can pass in an empty object for special characters:\n\n```typescript\nconst poemContent = createTelescopicTextFromBulletedList(content, {\n  specialCharacters: {},\n});\n```\n\n## Types\n\n```typescript\n// Default function to create a new `\u003cdiv\u003e` node containing the\n// telescoping text from bullet points\nfunction createTelescopicTextFromBulletedList(content: string, config?: Config);\n```\n\n## Future Work\n\nSee our issues page for all the features we're thinking about exploring. Some examples include:\n\n- Supporting infinite expansion with `...`\n- Concept of shapeshifting text in general... these are not always expansions.\n\n## Development\n\n- NOTE: avoid the usage of `export` keyword. it breaks in browser and we haven't figured out how to support it cross-function.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjackyzha0%2Ftelescopic-text","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjackyzha0%2Ftelescopic-text","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjackyzha0%2Ftelescopic-text/lists"}