From 851d68df832e6bb85697dfb0bb8d178e7ea15e6f Mon Sep 17 00:00:00 2001 From: Vladislav Kibenko Date: Thu, 30 Nov 2023 21:58:25 +0300 Subject: [PATCH 1/5] chore(readme): actualize solid router integration docs --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 8074c5e9e..71edded70 100644 --- a/README.md +++ b/README.md @@ -77,13 +77,14 @@ the [documentation](https://docs.telegram-mini-apps.com/platform/launch-paramete ### [`@tma.js/solid-router-integration`](https://docs.telegram-mini-apps.com/packages/typescript/tma-js-solid-router-integration) -[solid-router-integration-npm-badge]: https://img.shields.io/npm/v/@tma.js/solid-router-integration?logo=npm +[solid-router-integration-npm-badge]: https://img.shields.io/npm/v/@tma.js/solid-router-integration?logo=npm [![solid-router-integration-npm-badge]](https://npmjs.com/package/@tma.js/solid-router-integration) ![Size](https://img.shields.io/bundlephobia/minzip/@tma.js/solid-router-integration) [![code-badge]](https://github.com/Telegram-Mini-Apps/tma.js/tree/master/packages/solid-router-integration) -[@solidjs/router](https://www.npmjs.com/package/@solidjs/router) integration for navigation. +Telegram Mini Apps [Navigator](http://localhost:5173/packages/typescript/tma-js-sdk/navigation) +integration for [@solidjs/router](https://www.npmjs.com/package/@solidjs/router). ## Why not Telegram SDK From 1382b291cf31b2304a6d554fc5a99656485446cc Mon Sep 17 00:00:00 2001 From: Vladislav Kibenko Date: Thu, 30 Nov 2023 21:59:06 +0300 Subject: [PATCH 2/5] chore(solid-router-integration): update docs in readme --- packages/solid-router-integration/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/packages/solid-router-integration/README.md b/packages/solid-router-integration/README.md index dedb06f78..62bd7d52c 100644 --- a/packages/solid-router-integration/README.md +++ b/packages/solid-router-integration/README.md @@ -19,4 +19,5 @@ [![docs-badge]][solid-router-integration-docs-link] [![code-badge]][solid-router-integration-code-link] -[@solidjs/router](https://www.npmjs.com/package/@solidjs/router) integration for navigation. +Telegram Mini Apps [Navigator](http://localhost:5173/packages/typescript/tma-js-sdk/navigation) +integration for [@solidjs/router](https://www.npmjs.com/package/@solidjs/router). From e628eac38d23f56a37d481fac221c67d4098fc2e Mon Sep 17 00:00:00 2001 From: Vladislav Kibenko Date: Thu, 30 Nov 2023 22:36:07 +0300 Subject: [PATCH 3/5] docs(solid-router-integration): add solid-router-integration docs --- apps/docs/.vitepress/packages.ts | 10 +- .../tma-js-solid-router-integration.md | 163 ++++++++++++++++++ 2 files changed, 170 insertions(+), 3 deletions(-) create mode 100644 apps/docs/packages/typescript/tma-js-solid-router-integration.md diff --git a/apps/docs/.vitepress/packages.ts b/apps/docs/.vitepress/packages.ts index 360fc3052..8eacad5fc 100644 --- a/apps/docs/.vitepress/packages.ts +++ b/apps/docs/.vitepress/packages.ts @@ -42,15 +42,15 @@ export const packagesSidebar = { }, { text: 'InitData', - link: prefixed('/typescript/tma-js-sdk/init-data/init-data') + link: prefixed('/typescript/tma-js-sdk/init-data/init-data'), }, { text: 'Chat', - link: prefixed('/typescript/tma-js-sdk/init-data/chat') + link: prefixed('/typescript/tma-js-sdk/init-data/chat'), }, { text: 'User', - link: prefixed('/typescript/tma-js-sdk/init-data/user') + link: prefixed('/typescript/tma-js-sdk/init-data/user'), }, ], }, @@ -124,6 +124,10 @@ export const packagesSidebar = { }, { text: '@tma.js/sdk-react', link: prefixed('/typescript/tma-js-sdk-react') }, { text: '@tma.js/sdk-solid', link: prefixed('/typescript/tma-js-sdk-solid') }, + { + text: '@tma.js/solid-router-integration', + link: prefixed('/typescript/tma-js-solid-router-integration'), + }, ], }, { diff --git a/apps/docs/packages/typescript/tma-js-solid-router-integration.md b/apps/docs/packages/typescript/tma-js-solid-router-integration.md new file mode 100644 index 000000000..dc20f9177 --- /dev/null +++ b/apps/docs/packages/typescript/tma-js-solid-router-integration.md @@ -0,0 +1,163 @@ +# @tma.js/solid-router-integration + +

+ + + + + + + +

+ +Telegram Mini Apps [Navigator](tma-js-sdk/navigation.md) integration +for [@solidjs/router](https://www.npmjs.com/package/@solidjs/router). + +## Installation + +::: code-group + +```bash [pnpm] +pnpm i @tma.js/solid-router-integration +``` + +```bash [npm] +npm i @tma.js/solid-router-integration +``` + +```bash [yarn] +yarn add @tma.js/solid-router-integration +``` + +::: + +## Usage + +At the moment, this package provides the only 1 function, which creates the integration for +`@solidjs/router` Router - `createIntegration`. + +Here is how it could be used: + +```jsx +import { + Routes, + Route, + Navigate, + Router, +} from '@solidjs/router'; +import { HashNavigator } from '@tma.js/sdk'; +import { createIntegration } from '@tma.js/solid-router-integration'; + +import { IndexPage } from './IndexPage.js'; + +function App() { + // We should create navigator to pass it to integration creation. + const navigator = new HashNavigator([{}], 0); + + // Then, to allow this navigator update current browser history, + // we should attach it. Otherwise, it will work in memory mode. + void navigator.attach(); + + return ( + navigator)}> + + + }/> + + + ); +} +``` + +And also a bit more complex example with navigation state restoration: + +::: code-group + +```jsx [App.tsx] +import { + Routes, + Route, + Navigate, + Router, +} from '@solidjs/router'; +import { HashNavigator } from '@tma.js/sdk'; + +import { createNavigator } from './createNavigator.js'; +import { IndexPage } from './IndexPage.js'; + +function App() { + // We should create navigator to pass it to integration creation. + const navigator = createNavigator(); + + // Then, to allow this navigator update current browser history, + // we should attach it. Otherwise, it will work in memory mode. + void navigator.attach(); + + return ( + navigator)}> + + + }/> + + + ); +} +``` + +```typescript [createNavigator.ts] +import { + retrieveLaunchData, + HashNavigator, + type HashNavigatorOptions, +} from '@tma.js/sdk'; + +export function createNavigator(): HashNavigator { + let navigator: HashNavigator | undefined; + const navigatorOptions: HashNavigatorOptions = { + debug: true, + }; + + // If page was reloaded, we assume that navigator had to previously save + // its state in the session storage. + if (retrieveLaunchData().isPageReload) { + const stateRaw = sessionStorage.getItem('hash-navigator-state'); + if (stateRaw) { + try { + const { cursor, entries } = JSON.parse(stateRaw); + navigator = new HashNavigator(entries, cursor, navigatorOptions); + } catch (e) { + console.error('Unable to restore hash navigator state.', e); + } + } + } + + // In case, we could not restore its state, or it is the fresh start, we + // can create empty navigator. + if (!navigator) { + navigator = new HashNavigator([{}], 0, navigatorOptions); + } + + const saveState = (nav: HashNavigator) => { + sessionStorage.setItem('hash-navigator-state', JSON.stringify({ + cursor: nav.cursor, + entries: nav.getEntries(), + })); + } + + // Whenever navigator changes its state, we save it in the session storage. + navigator.on('change', ({ navigator: nav }) => saveState(nav)); + + // Save initial state to make sure nothing will break when page will + // be reloaded. + saveState(navigator); + + return navigator; +} +``` + +::: + +## Template + +We have already created a [template](https://github.com/Telegram-Mini-Apps/solidjs-template) for +Solid JS that utilizes the current package, so you can use it. From e31ed2471eb320e2ddf76c1ea2122d673e005440 Mon Sep 17 00:00:00 2001 From: Vladislav Kibenko Date: Thu, 30 Nov 2023 22:37:23 +0300 Subject: [PATCH 4/5] docs(packages): add links to source code and bundle size for some packages --- .../packages/typescript/tma-js-sdk-react.md | 14 +++++++++----- .../packages/typescript/tma-js-sdk-solid.md | 19 ++++++++++++++----- .../packages/typescript/tma-js-sdk/about.md | 14 +++++++++----- 3 files changed, 32 insertions(+), 15 deletions(-) diff --git a/apps/docs/packages/typescript/tma-js-sdk-react.md b/apps/docs/packages/typescript/tma-js-sdk-react.md index 2a48cb41f..8403fb73d 100644 --- a/apps/docs/packages/typescript/tma-js-sdk-react.md +++ b/apps/docs/packages/typescript/tma-js-sdk-react.md @@ -4,11 +4,15 @@ outline: [2, 3] # @tma.js/sdk-react -[npm-link]: https://npmjs.com/package/@tma.js/sdk-react - -[npm-shield]: https://img.shields.io/npm/v/@tma.js/sdk-react?logo=npm - -![[npm-link]][npm-shield] +

+ + + + + + + +

React JS bindings for [client SDK](tma-js-sdk/about.md). Includes hooks, components and utilities for comfortable usage of React JS on the Telegram Mini Apps platform. diff --git a/apps/docs/packages/typescript/tma-js-sdk-solid.md b/apps/docs/packages/typescript/tma-js-sdk-solid.md index cd395e249..a7f181bad 100644 --- a/apps/docs/packages/typescript/tma-js-sdk-solid.md +++ b/apps/docs/packages/typescript/tma-js-sdk-solid.md @@ -4,11 +4,15 @@ outline: [2, 3] # @tma.js/sdk-solid -[npm-link]: https://npmjs.com/package/@tma.js/sdk-solid - -[npm-shield]: https://img.shields.io/npm/v/@tma.js/sdk-solid?logo=npm - -![[npm-link]][npm-shield] +

+ + + + + + + +

Solid JS bindings for [client SDK](tma-js-sdk/about.md). Includes hooks, components and utilities for comfortable usage of Solid JS on the Telegram Mini Apps platform. @@ -336,3 +340,8 @@ their properties change. Using these hooks with an uninitialized SDK will result in throwing a corresponding error. ::: + +## Template + +We have already created a [template](https://github.com/Telegram-Mini-Apps/solidjs-template) for +Solid JS that utilizes the current package, so you can use it. \ No newline at end of file diff --git a/apps/docs/packages/typescript/tma-js-sdk/about.md b/apps/docs/packages/typescript/tma-js-sdk/about.md index 950e1c555..c4b427741 100644 --- a/apps/docs/packages/typescript/tma-js-sdk/about.md +++ b/apps/docs/packages/typescript/tma-js-sdk/about.md @@ -1,10 +1,14 @@ # @tma.js/sdk -[npm-link]: https://npmjs.com/package/@tma.js/sdk - -[npm-shield]: https://img.shields.io/npm/v/@tma.js/sdk?logo=npm - -![[npm-link]][npm-shield] +

+ + + + + + + +

Made from scratch TypeScript library for seamless communication with Telegram Mini Apps functionality. From 04d2b186298bbc44fcb4d5ffa2e365c6e1791acd Mon Sep 17 00:00:00 2001 From: Vladislav Kibenko Date: Thu, 30 Nov 2023 22:46:34 +0300 Subject: [PATCH 5/5] docs(changeset): The first package major version --- .changeset/thin-trees-decide.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/thin-trees-decide.md diff --git a/.changeset/thin-trees-decide.md b/.changeset/thin-trees-decide.md new file mode 100644 index 000000000..07b4bc92f --- /dev/null +++ b/.changeset/thin-trees-decide.md @@ -0,0 +1,5 @@ +--- +"@tma.js/solid-router-integration": major +--- + +The first package major version