From f70c448b8d1584024245b6a5844eca1e07e6e502 Mon Sep 17 00:00:00 2001 From: Ilya Azin Date: Sat, 17 Sep 2022 13:31:03 +0300 Subject: [PATCH 01/10] feat(overview): move intro content to GetStarted (en) DISCOVERY-335 --- README.md | 2 +- .../current/about/promote/integration.mdx | 2 +- .../current/get-started/basics.md | 142 --------------- .../current/get-started/index.mdx | 6 +- .../current/get-started/overview.md | 172 ++++++++++++++++++ .../current/intro.mdx | 89 +-------- i18n/en/docusaurus-theme-classic/footer.json | 2 +- src/features/header/ui.jsx | 2 +- src/pages/versions/index.jsx | 2 +- 9 files changed, 183 insertions(+), 236 deletions(-) delete mode 100644 i18n/en/docusaurus-plugin-content-docs/current/get-started/basics.md create mode 100644 i18n/en/docusaurus-plugin-content-docs/current/get-started/overview.md diff --git a/README.md b/README.md index c811ba051d..c2953fd182 100644 --- a/README.md +++ b/README.md @@ -238,7 +238,7 @@ If there are variations, how best to place indents-welcome:) [refs-contributing]: CONTRIBUTING.md -[refs-docs]: https://feature-sliced.design/docs/intro +[refs-docs]: https://feature-sliced.design/docs [refs-motivation]: https://feature-sliced.design/docs/about/motivation [refs-motivation-why]: https://feature-sliced.design/docs/about/motivation#-почему-не-хватает-существующих-решений diff --git a/i18n/en/docusaurus-plugin-content-docs/current/about/promote/integration.mdx b/i18n/en/docusaurus-plugin-content-docs/current/about/promote/integration.mdx index cc3189c22c..cc29cd4d75 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/about/promote/integration.mdx +++ b/i18n/en/docusaurus-plugin-content-docs/current/about/promote/integration.mdx @@ -13,7 +13,7 @@ First 5 minutes (RU): ## Also **Advantages**: -- [Overview](/docs/intro#overview) +- [Overview](/docs/get-started/overview) - CodeReview - Onboarding diff --git a/i18n/en/docusaurus-plugin-content-docs/current/get-started/basics.md b/i18n/en/docusaurus-plugin-content-docs/current/get-started/basics.md deleted file mode 100644 index 93645469cd..0000000000 --- a/i18n/en/docusaurus-plugin-content-docs/current/get-started/basics.md +++ /dev/null @@ -1,142 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Basics - -:::caution - -Only basic information on the methodology is presented here - -For a more competent application, it is worth getting acquainted with each concept in more detail in the corresponding section of the documentation - -::: - -## Concepts - -### [`Public API`][refs-public-api] - -Each module must have a **declaration of its public API** at the top level - -- To connect to other modules, without the need to refer to the internal structure of this module -- To isolate the implementation details from the consumer modules -- Also, the Public API should protect the module interface after refactoring - in order to avoid unforeseen consequences - -### [`Isolation`][refs-isolation] - -The module should not **depend directly** on other modules of the same layer or overlying layers - -- The concept is also known as [Low Coupling & High Cohesion][refs-low-coupling] - to prevent implicit connections / side effects during development and refactoring - -### [`Needs driven`][refs-needs-driven] - -Orientation **to the needs of the business and the user** - -- Also includes splitting the structure by business domains *(["layers"][refs-splitting-layers] and ["slices"][refs-splitting-slices])* - -## Abstractions - -For [architecture design][refs-splitting] the methodology suggests operating with [familiar abstractions][refs-adaptability], but in a more consistent and consistent order. - -### [`Layers`][refs-splitting-layers] - -The first level of abstraction is **according to the scope of influence** - -- `app` - initializing the application *(init, styles, providers,...)* -- `processes` - the business processes of the application control pages *(payment, auth, ...)* -- `pages` application page *(user-page, ...)* -- `features` - part of application functionality *(auth-by-oauth, ...)* -- `entities` - the business entity *(viewer, order, ...)* -- `shared` - reusable infrastructure code *(UIKit, libs, API, ...)* - -### [`Slices`][refs-splitting-slices] - -The second level of abstraction is **according to the business domain** - -The rules by which the code is divided into slices *depend on the specific project and its business rules* and are not determined by the methodology - -### [`Segments`][refs-splitting-segments] - -The third level of abstraction is **according to the purpose in the implementation** - -- `ui` - UI-representation of the module *(components, widgets, canvas,...)* -- `model` - business logic of the module *(store, effects/actions, hooks/contracts,...)* -- `lib` - auxiliary libraries -- `api` - the logic of interaction with the API -- `config` - the configuration module of the application and its environment - -:::note - -In most cases, [it is recommended][ext-disc-api] to place `api` and `config` only in the shared layer - -::: - -## Structure - -```sh -└── src/ - ├── app/ # Layer: Application - | # - ├── processes/ # Layer: Processes (optional) - | ├── {some-process}/ # Slice: (e.g. CartPayment process) - | | ├── lib/ # Segment: Infrastructure-logic (helpers/utils) - | | └── model/ # Segment: Business Logic - | ... # - | # - ├── pages/ # Layer: Pages - | ├── {some-page}/ # Slice: (e.g. ProfilePage page) - | | ├── lib/ # Segment: Infrastructure-logic (helpers/utils) - | | ├── model/ # Segment: Business Logic - | | └── ui/ # Segment: UI logic - | ... # - | # - ├── widgets/ # Layer: Widgets - ├── {some-widget}/ # Slice: (e.g. Header widget) - | | ├── lib/ # Segment: Infrastructure-logic (helpers/utils) - | | ├── model/ # Segment: Business Logic - | | └── ui/ # Segment: UI logic - ├── features/ # Layer: Features - | ├── {some-feature}/ # Slice: (e.g. AuthByPhone feature) - | | ├── lib/ # Segment: Infrastructure-logic (helpers/utils) - | | ├── model/ # Segment: Business Logic - | | └── ui/ # Segment: UI logic - | ... # - | # - ├── entities/ # Layer: Business Entities - | ├── {some-entity}/ # Slice: (e.g. entity User) - | | ├── lib/ # Segment: Infrastructure-logic (helpers/utils) - | | ├── model/ # Segment: Business Logic - | | └── ui/ # Segment: UI logic - | ... # - | # - ├── shared/ # Layer: Reused resources - | ├── api/ # Segment: Logic of API requests - | ├── config/ # Segment: Application configuration - | ├── lib/ # Segment: Infrastructure-application logic - | └── ui/ # Segment: UIKit of the application - | ... # - | # - └── index.tsx/ # -``` - -## See also - -- [(Section) Fundamental concepts of the methodology][refs-concepts] -- [(Section) Guides and examples on the application of the methodology][refs-guides] -- [(Article) About splitting the logic in the application. Modularization][refs-splitting] - -[ext-disc-api]: https://github.com/feature-sliced/documentation/discussions/66 - -[refs-concepts]: /docs/concepts -[refs-public-api]: /docs/concepts/public-api -[refs-isolation]: /docs/concepts/cross-communication -[refs-needs-driven]: /docs/concepts/needs-driven -[refs-adaptability]: /docs/concepts/naming-adaptability - -[refs-splitting]: /docs/concepts/app-splitting -[refs-splitting-layers]: /docs/concepts/app-splitting#group-layers -[refs-splitting-slices]: /docs/concepts/app-splitting#group-slices -[refs-splitting-segments]: /docs/concepts/app-splitting#group-segments - -[refs-guides]: /docs/guides -[refs-low-coupling]: /docs/concepts/low-coupling diff --git a/i18n/en/docusaurus-plugin-content-docs/current/get-started/index.mdx b/i18n/en/docusaurus-plugin-content-docs/current/get-started/index.mdx index 7a9ff24199..b3be2459fd 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/get-started/index.mdx +++ b/i18n/en/docusaurus-plugin-content-docs/current/get-started/index.mdx @@ -20,9 +20,9 @@ import Row from "@site/src/shared/ui/row/tmpl.mdx" import { RocketOutlined, BuildOutlined, SettingOutlined } from "@ant-design/icons"; + +## Basics + +In FSD, a [project consists][refs-splitting] of layers, each layer is made up of slices and each slice is made up of segments. + +![themed--scheme](/img/visual_schema.jpg) + +The layers are standardized across all projects and vertically arranged. Modules on one layer can only interact with modules from the layers strictly below. There are currently seven of them (bottom to top): + +1. `shared` — reusable functionality, detached from the specifics of the project/business. + (e.g. UIKit, libs, API) +2. `entities` — business entities. + (e.g., User, Product, Order) +3. `features` — user interactions, actions that bring business value to the user. + (e.g. SendComment, AddToCart, UsersSearch) +4. `widgets` — compositional layer to combine entities and features into meaningful blocks. + (e.g. IssuesList, UserProfile) +5. `pages` — compositional layer to construct full pages from entities, features and widgets. +6. `processes` — complex inter-page scenarios. + (e.g., authentication) +7. `app` — app-wide settings, styles and providers. + + +Then there are slices, which partition the code by business domain. This makes your codebase easy to navigate by keeping logically related modules close together. Slices cannot use other slices on the same layer, and that helps with high cohesion and low coupling. + +Each slice, in turn, consists of segments. These are tiny modules that are meant to help with separating code within a slice by its technical purpose. The most common segments are `ui`, `model` (store, actions), `api` and `lib` (utils/hooks), but you can omit some or add more, as you see fit. + +:::note + +In most cases, [it is recommended][ext-disc-api] to place `api` and `config` only in the shared layer + +::: + +**Also, FSD have few core-concepts:** +- [Public API][refs-public-api] - each module must have a *declaration of its public API* at the top level - without access to internal structure of modules with isolation of implementation +- [Isolation][refs-isolation] (Low Coupling & High Cohesion) - the module should not *depend directly* on other modules of the same layer or overlying layers (to prevent implicit connections and side effects during development and refactoring) +- [Domain Driven][refs-needs-driven] - orientation *to the needs of the business and the user* with [app splitting][refs-splitting] by business domains + +## Example + +Let's consider a social network application. + +* `app/` contains setup of routing, store and global styles. +* `processes/` contains the part of authentication that is responsible for reading/writing authentication tokens. +* `pages/` contains the route components for each page in the app, mostly composition, hardly any logic. + +Within that application, let's consider a post card in a news feed. + +* `widgets/` contains the "assembled" post card, with content and interactive buttons that are wired up to the relevant calls on the back-end. +* `features/` contains the interactivity of the card (e.g., like button) and the logic of processing those interactions. +* `entities/` contains the shell of the card with slots for content and the interactive elements. The tile representing the post author is also here, but in a different slice. + + +```sh +└── src/ + ├── app/ # Layer: Application + | # + ├── processes/ # Layer: Processes (optional) + | ├── {some-process}/ # Slice: (e.g. CartPayment process) + | | ├── lib/ # Segment: Utility logic (utils/hooks) + | | └── model/ # Segment: Business Logic + | ... # + ├── pages/ # Layer: Pages + | ├── {some-page}/ # Slice: (e.g. ProfilePage page) + | | ├── lib/ # Segment: Utility logic (utils/hooks) + | | ├── model/ # Segment: Business Logic + | | └── ui/ # Segment: UI logic + | ... # + ├── widgets/ # Layer: Widgets + | ├── {some-widget}/ # Slice: (e.g. Header widget) + | | ├── lib/ # Segment: Utility logic (utils/hooks) + | | ├── model/ # Segment: Business Logic + | | └── ui/ # Segment: UI logic + | ... # + ├── features/ # Layer: Features + | ├── {some-feature}/ # Slice: (e.g. AuthByPhone feature) + | | ├── lib/ # Segment: Utility logic (utils/hooks) + | | ├── model/ # Segment: Business Logic + | | └── ui/ # Segment: UI logic + | ... # + ├── entities/ # Layer: Business Entities + | ├── {some-entity}/ # Slice: (e.g. entity User) + | | ├── lib/ # Segment: Utility logic (utils/hooks) + | | ├── model/ # Segment: Business Logic + | | └── ui/ # Segment: UI logic + | ... # + ├── shared/ # Layer: Reused resources + | ├── api/ # Segment: Logic of API requests + | ├── config/ # Segment: Application configuration + | ├── lib/ # Segment: General utility logic + | └── ui/ # Segment: UIKit of the application + | ... # + └── index.tsx/ # +``` + +## Advantages + +- **Uniformity** + The code is organized by scope of influence (layers), by domain (slices), and by technical purpose (segments). + This creates a standardized architecture that is easier to comprehend for newcomers. + +- **Controlled reuse of logic** + Each architectural component has its purpose and predictable dependencies. + This keeps a balance between following the **DRY** principle and adaptation possibilities. + +- **Stability in face of changes and refactoring** + A module on a particular layer cannot use other modules on the same layer, or the layers above. + This enables isolated modifications without unforeseen consequences. + + +## Incremental adoption + +The power of FSD lies in _structured_ decomposition. At its finest, it enables to locate any part of code near-deterministically. However, the level of decomposition is a parameter, and each team can tweak it to strike a balance between simple adoption and the amount of benefits. + +Here's a proposed strategy to migrate an existing codebase to FSD, based on experience: + +1. Start by outlining the `app` and `shared` layers to create a foundation. Usually, these layers are the smallest. + +2. Distribute all of the existing UI across `widgets` and `pages`, even if they have dependencies that violate the rules of FSD. + +3. Start gradually increasing the precision of decomposition by separating `features` and `entities`, turning pages and widgets from logic-bearing layers into purely compositional layers. + +It's advised to refrain from adding new large entities while refactoring or refactoring only certain parts of the project. + +## See also + +- [(Section) Fundamental concepts of the methodology][refs-concepts] +- [(Section) Guides and examples on the application of the methodology][refs-guides] +- [(Article) About splitting the logic in the application. Modularization][refs-splitting] + +[ext-disc-api]: https://github.com/feature-sliced/documentation/discussions/66 + +[refs-concepts]: /docs/concepts +[refs-public-api]: /docs/concepts/public-api +[refs-isolation]: /docs/concepts/cross-communication +[refs-needs-driven]: /docs/concepts/needs-driven +[refs-adaptability]: /docs/concepts/naming-adaptability + +[refs-splitting]: /docs/concepts/app-splitting +[refs-splitting-layers]: /docs/concepts/app-splitting#group-layers +[refs-splitting-slices]: /docs/concepts/app-splitting#group-slices +[refs-splitting-segments]: /docs/concepts/app-splitting#group-segments + +[refs-guides]: /docs/guides +[refs-low-coupling]: /docs/concepts/low-coupling +[refs-examples]: /examples +[refs-clean-architecture]: https://medium.com/codex/clean-architecture-for-dummies-df6561d42c94 diff --git a/i18n/en/docusaurus-plugin-content-docs/current/intro.mdx b/i18n/en/docusaurus-plugin-content-docs/current/intro.mdx index c16d79f968..2c158f4496 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/intro.mdx +++ b/i18n/en/docusaurus-plugin-content-docs/current/intro.mdx @@ -1,94 +1,15 @@ --- sidebar_position: 1 +slug: / pagination_next: get-started/index --- -# 🔎 Intro - -OVERVIEW-ORIENTED +# Documentation ![feature-sliced-banner](/img/banner.jpg) **Feature-Sliced Design** (FSD) is an architectural methodology for scaffolding front-end applications. Simply put, it's a compilation of rules and conventions on organizing code. The main purpose of this methodology is to make the project more understandable and structured in the face of ever-changing business requirements. -## Is it right for me? - -FSD can be implemented in projects and teams of any size, but there are a few things to keep in mind: - -- This methodology is for front-end projects only. If you're looking for a back-end architecture, consider [Clean Architecture][refs-clean-architecture]. -- A very simple app of a single page might not need the benefits of FSD and suffer from the overhead. However, FSD promotes a nice way of thinking, so feel free to use on the tiniest projects if you want. -- A huge app, the size of the Google Cloud admin dashboard, will require a custom architecture. It could still be based on FSD, by the way. - -FSD doesn't enforce a particular programming language, UI framework or state manager — bring your own or see some [examples][refs-examples]. - -If you have an existing project, fear not — FSD can be adopted incrementally. Just make sure that your team is **in pain** from the current architecture, otherwise a switch might not be worth it. - -## Overview - -In FSD, a project consists of _layers_, each layer is made up of _slices_ and each slice is made up of _segments_. - -![themed--scheme](/img/visual_schema.jpg) - -The layers are standardized across all projects and vertically arranged. Modules on one layer can only interact with modules from the layers strictly below. There are currently seven of them (bottom to top): - -1. **Shared** — reusable functionality, detached from the specifics of the project/business. -2. **Entities** — business entities (e.g., User, Product, Order). -3. **Features** — user interactions, actions that bring business value to the user. -4. **Widgets** — compositional layer to combine entities and features into meaningful blocks. -5. **Pages** — compositional layer to construct full pages from entities, features and widgets. -6. **Processes** — complex inter-page scenarios (e.g., authentication). -7. **App** — app-wide settings, styles and providers. - -Then there are slices, which partition the code by business domain. This makes your codebase easy to navigate by keeping logically related modules close together. Slices cannot use other slices on the same layer, and that helps with high cohesion and low coupling. - -Each slice, in turn, consists of segments. These are tiny modules that are meant to help with separating code within a slice by its technical purpose. The most common segments are `ui`, `model`, `api` and `lib`, but you can omit some or add more, as you see fit. - -### Decomposition example - -Let's consider a social network application. - -* `app/` contains setup of routing, store and global styles. -* `processes/` contains the part of authentication that is responsible for reading/writing authentication tokens. -* `pages/` contains the route components for each page in the app, mostly composition, hardly any logic. - -Within that application, let's consider a post card in a news feed. - -* `widgets/` contains the "assembled" post card, with content and interactive buttons that are wired up to the relevant calls on the back-end. -* `features/` contains the interactivity of the card (e.g., like button) and the logic of processing those interactions. -* `entities/` contains the shell of the card with slots for content and the interactive elements. The tile representing the post author is also here, but in a different slice. - -### Advantages - -- **Uniformity** - The code is organized by scope of influence (layers), by domain (slices), and by technical purpose (segments). - This creates a standardized architecture that is easier to comprehend for newcomers. - -- **Controlled reuse of logic** - Each architectural component has its purpose and predictable dependencies. - This keeps a balance between following the **DRY** principle and adaptation possibilities. - -- **Stability in face of changes and refactoring** - A module on a particular layer cannot use other modules on the same layer, or the layers above. - This enables isolated modifications without unforeseen consequences. - - -## Incremental adoption - -The power of FSD lies in _structured_ decomposition. At its finest, it enables to locate any part of code near-deterministically. However, the level of decomposition is a parameter, and each team can tweak it to strike a balance between simple adoption and the amount of benefits. - -Here's a proposed strategy to migrate an existing codebase to FSD, based on experience: - -1. Start by outlining the `app` and `shared` layers to create a foundation. Usually, these layers are the smallest. - -2. Distribute all of the existing UI across `widgets` and `pages`, even if they have dependencies that violate the rules of FSD. - -3. Start gradually increasing the precision of decomposition by separating `features` and `entities`, turning pages and widgets from logic-bearing layers into purely compositional layers. - -It's advised to refrain from adding new large entities while refactoring or refactoring only certain parts of the project. - - -## What's next? - import Row from "@site/src/shared/ui/row/tmpl.mdx" import { RocketOutlined, ThunderboltOutlined, FundViewOutlined } from "@ant-design/icons"; import Link from "@docusaurus/Link"; @@ -98,7 +19,7 @@ import Link from "@docusaurus/Link"; description="A tour over the basic concepts and structure as well as a comprehensive review of a React sample project" to="/docs/get-started" Icon={"🚀"} - tags={['Basics', 'Quick start', 'FAQ']} + tags={['Overview', 'Quick start', 'FAQ']} /> - -[refs-examples]: /examples - -[refs-clean-architecture]: https://medium.com/codex/clean-architecture-for-dummies-df6561d42c94 diff --git a/i18n/en/docusaurus-theme-classic/footer.json b/i18n/en/docusaurus-theme-classic/footer.json index f129408d11..48cb65f586 100644 --- a/i18n/en/docusaurus-theme-classic/footer.json +++ b/i18n/en/docusaurus-theme-classic/footer.json @@ -13,7 +13,7 @@ }, "link.item.label.Documentation": { "message": "Documentation", - "description": "The label of footer link with label=Documentation linking to /docs/intro" + "description": "The label of footer link with label=Documentation linking to /docs" }, "link.item.label.Discussions": { "message": "Discussions", diff --git a/src/features/header/ui.jsx b/src/features/header/ui.jsx index f9d99ba833..ff164691cc 100644 --- a/src/features/header/ui.jsx +++ b/src/features/header/ui.jsx @@ -14,7 +14,7 @@ export function Header() {

{siteConfig.title}

{translate({ id: "features.hero.tagline" })}

- + {translate({ id: "features.hero.get_started" })} diff --git a/src/pages/versions/index.jsx b/src/pages/versions/index.jsx index b8887f78e7..bfa7ff1d2f 100644 --- a/src/pages/versions/index.jsx +++ b/src/pages/versions/index.jsx @@ -39,7 +39,7 @@ function Version() { hrefTitle="Release Notes" > - Documentation + Documentation From 2539eab0b27831572d521d2ec6009f237397c27d Mon Sep 17 00:00:00 2001 From: Ilya Azin Date: Sat, 17 Sep 2022 13:42:51 +0300 Subject: [PATCH 02/10] feat(overview): move intro content to GetStarted (ru) DISCOVERY-335 --- .../current/get-started/overview.md | 5 - .../current/about/promote/integration.mdx | 2 +- .../current/get-started/basics.md | 144 -------------- .../current/get-started/index.mdx | 4 +- .../current/get-started/overview.md | 188 ++++++++++++++++++ .../current/intro.mdx | 88 +------- i18n/ru/docusaurus-theme-classic/footer.json | 2 +- src/app/index.scss | 13 +- 8 files changed, 204 insertions(+), 242 deletions(-) delete mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/get-started/basics.md create mode 100644 i18n/ru/docusaurus-plugin-content-docs/current/get-started/overview.md diff --git a/i18n/en/docusaurus-plugin-content-docs/current/get-started/overview.md b/i18n/en/docusaurus-plugin-content-docs/current/get-started/overview.md index 5e62902aef..3584370eb0 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/get-started/overview.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/get-started/overview.md @@ -159,14 +159,9 @@ It's advised to refrain from adding new large entities while refactoring or refa [refs-public-api]: /docs/concepts/public-api [refs-isolation]: /docs/concepts/cross-communication [refs-needs-driven]: /docs/concepts/needs-driven -[refs-adaptability]: /docs/concepts/naming-adaptability [refs-splitting]: /docs/concepts/app-splitting -[refs-splitting-layers]: /docs/concepts/app-splitting#group-layers -[refs-splitting-slices]: /docs/concepts/app-splitting#group-slices -[refs-splitting-segments]: /docs/concepts/app-splitting#group-segments [refs-guides]: /docs/guides -[refs-low-coupling]: /docs/concepts/low-coupling [refs-examples]: /examples [refs-clean-architecture]: https://medium.com/codex/clean-architecture-for-dummies-df6561d42c94 diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/about/promote/integration.mdx b/i18n/ru/docusaurus-plugin-content-docs/current/about/promote/integration.mdx index 6083b4387e..edcc78549a 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/about/promote/integration.mdx +++ b/i18n/ru/docusaurus-plugin-content-docs/current/about/promote/integration.mdx @@ -13,7 +13,7 @@ sidebar_position: 1 ## Также {#also} **Преимущества**: -- [Overview](/docs/intro#overview) +- [Overview](/docs/get-started/overview#advantages) - CodeReview - Onboarding diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/get-started/basics.md b/i18n/ru/docusaurus-plugin-content-docs/current/get-started/basics.md deleted file mode 100644 index 788483c54f..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/get-started/basics.md +++ /dev/null @@ -1,144 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Основы {#basics} - -:::caution Предупреждение - -Здесь представлена лишь основная информация по методологии - -Для более грамотного применения, стоит ознакомится детальней с каждым понятием в соответствующем разделе документации - -::: - -## Концепции {#concepts} - -### [`Public API`][refs-public-api] - -Каждый модуль должен иметь на верхнем уровне **декларацию своего публичного API** - -- Для подключения в другие модули, без нужды обращаться к внутренней структуре данного модуля -- Для изоляции деталей реализации от модулей-потребителей -- Также Public API должен защищать интерфейс модуля после рефакторинга - во избежание непредвиденных последствий - -### [`Isolation`][refs-isolation] - -Модуль не должен **зависеть напрямую** от других модулей того же слоя или вышележаших слоев - -- Концепция известна также как [Low Coupling & High Cohesion][refs-low-coupling] - для предотвращения неявных связей / сайд-эффектов при разработке и рефакторинге - -### [`Needs driven`][refs-needs-driven] - -Ориентирование **на потребности бизнеса и пользователя** - -- Включает в себя также разбиение структуры по бизнес-доменам *(["слоям"][refs-splitting-layers] и ["слайсам"][refs-splitting-slices])* - -## Абстракции {#abstractions} - -Для [проектирования архитектуры][refs-splitting] методология предлагает оперировать [привычными абстракциями][refs-adaptability], но в более консистентном и последовательном порядке. - -### [`Layers`][refs-splitting-layers] - -Первый уровень абстрагирования - **согласно скоупу влияния** - -- `app` - инициализация приложения *(init, styles, providers, ...)* -- `processes` - бизнес-процессы приложения управляющие страницами *(payment, auth, ...)* -- `pages` - страницы приложения *(user-page, ...)* -- `features` - части функциональности приложения *(auth-by-oauth, ...)* -- `entities` - бизнес-сущности *(viewer, order, ...)* -- `shared` - переиспользуемый инфраструктурный код *(UIKit, libs, API, ...)* - -### [`Slices`][refs-splitting-slices] - -Второй уровень абстрагирования - **согласно бизнес-домену** - -Правила, по которым код разделяется на слайсы, *зависят от конкретного проекта и его бизнес-правил* и не определяются методологией - -### [`Segments`][refs-splitting-segments] - -Третий уровень абстрагирования - **согласно назначению в реализации** - -- `ui` - UI-представление модуля *(components, widgets, canvas, ...)* -- `model` - бизнес-логика модуля *(store, effects/actions, hooks/contracts, ...)* -- `lib` - вспомогательные библиотеки -- `api` - логика взаимодействия с API -- `config` - модуль конфигурации приложения и его окружения - -:::note - -В большинстве случаев [рекомендуется][ext-disc-api] располагать `api` и `config` только в shared-слое - -::: - -## Структура {#structure} - -```sh -└── src/ - ├── app/ # Layer: Приложение - | # - ├── processes/ # Layer: Процессы (опционально) - | ├── {some-process}/ # Slice: (н-р процесс CartPayment) - | | ├── lib/ # Segment: Инфраструктурная-логика (helpers/utils) - | | └── model/ # Segment: Бизнес-логика - | ... # - | # - ├── pages/ # Layer: Страницы - | ├── {some-page}/ # Slice: (н-р страница ProfilePage) - | | ├── lib/ # Segment: Инфраструктурная-логика (helpers/utils) - | | ├── model/ # Segment: Бизнес-логика - | | └── ui/ # Segment: UI-логика - | ... # - | # - ├── widgets/ # Layer: Виджеты - | ├── {some-widget}/ # Slice: (н-р виджет Header) - | | ├── lib/ # Segment: Инфраструктурная-логика (helpers/utils) - | | ├── model/ # Segment: Бизнес-логика - | | └── ui/ # Segment: UI-логика - | ... # - | # - ├── features/ # Layer: Фичи - | ├── {some-feature}/ # Slice: (н-р фича AuthByPhone) - | | ├── lib/ # Segment: Инфраструктурная-логика (helpers/utils) - | | ├── model/ # Segment: Бизнес-логика - | | └── ui/ # Segment: UI-логика - | ... # - | # - ├── entities/ # Layer: Бизнес-сущности - | ├── {some-entity}/ # Slice: (н-р сущность User) - | | ├── lib/ # Segment: Инфраструктурная-логика (helpers/utils) - | | ├── model/ # Segment: Бизнес-логика - | | └── ui/ # Segment: UI-логика - | ... # - | # - ├── shared/ # Layer: Переиспользуемые ресурсы - | ├── api/ # Segment: Логика запросов к API - | ├── config/ # Segment: Конфигурация приложения - | ├── lib/ # Segment: Инфраструктурная-логика приложения - | └── ui/ # Segment: UIKit приложения - | ... # - | # - └── index.tsx/ # -``` - -## См. также {#see-also} - -- [(Раздел) Фундаментальные концепции методологии][refs-concepts] -- [(Раздел) Гайды и примеры по применению методологии][refs-guides] -- [(Статья) Про разбиение логики в приложении. Модуляризация][refs-splitting] - -[ext-disc-api]: https://github.com/feature-sliced/documentation/discussions/66 - -[refs-concepts]: /docs/concepts -[refs-public-api]: /docs/concepts/public-api -[refs-isolation]: /docs/concepts/cross-communication -[refs-needs-driven]: /docs/concepts/needs-driven -[refs-adaptability]: /docs/concepts/naming-adaptability - -[refs-splitting]: /docs/concepts/app-splitting -[refs-splitting-layers]: /docs/concepts/app-splitting#group-layers -[refs-splitting-slices]: /docs/concepts/app-splitting#group-slices -[refs-splitting-segments]: /docs/concepts/app-splitting#group-segments - -[refs-guides]: /docs/guides -[refs-low-coupling]: /docs/concepts/low-coupling diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/get-started/index.mdx b/i18n/ru/docusaurus-plugin-content-docs/current/get-started/index.mdx index 622b804a04..0f07b0d390 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/get-started/index.mdx +++ b/i18n/ru/docusaurus-plugin-content-docs/current/get-started/index.mdx @@ -20,8 +20,8 @@ import Row from "@site/src/shared/ui/row/tmpl.mdx" import { RocketOutlined, BuildOutlined, SettingOutlined } from "@ant-design/icons"; diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/get-started/overview.md b/i18n/ru/docusaurus-plugin-content-docs/current/get-started/overview.md new file mode 100644 index 0000000000..e7125d0405 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/get-started/overview.md @@ -0,0 +1,188 @@ +--- +sidebar_position: 1 +--- + +# Основы {#basics} + +:::caution Предупреждение + +Здесь представлена лишь основная информация по методологии + +Для более грамотного применения, стоит ознакомится детальней с каждым понятием в соответствующем разделе документации + +::: + + +## Подходит ли это мне? {#is-it-right-for-me} + +FSD подходит для проектов и команд любого размера с некоторыми оговорками: + +- Эта методология исключительно для фронтенда. Если вы ищете архитектуру для бэкенда, обратите внимание на [Clean Architecture][refs-clean-architecture]. +- Если вы разрабатываете очень простое приложение из одной странички на FSD, преимущества методологии вряд ли понадобятся, а вот разработка может замедлиться. Однако, FSD помогает стандартизированно мыслить о фронтенд-приложениях, так что смело используйте даже на маленьких проектах, если знаете, для чего она вам. +- Огромное приложение, соизмеримое с админ-панелью Google Cloud, потребует специализированной архитектуры. FSD в данном случае может выступать в качестве отправной точки. + +Методология не привязана к конкретному языку программирования, UI-фреймворку или менеджеру состояния — подойдет любой (см. [примеры использования][refs-examples]). + +Если у вас уже есть проект, не переживайте — FSD можно внедрять постепенно. Главный вопрос, который стоит задать команде: "**Eсть ли боль** при разработке проекта?" Если боли нет, возможно, переход делать не стоит. + + +## Основы {#basics} + +Проект на FSD состоит из слоев (layers), каждый слой состоит из слайсов (slices) и каждый слайс состоит из слайсов (segments). + +![themed--scheme](/img/visual_schema.jpg) + +Слои стандартизированы во всех проектах и расположены вертикально. Модули на одном слое могут взаимодействовать лишь с модулями, находящимися на слоях строго ниже. На данный момент слоев семь (снизу вверх): + +1. `shared` — переиспользуемый код, не имеющий отношения к специфике приложения/бизнеса. + (например, UIKit, libs, API) +2. `entities` (сущности) — бизнес-сущности (например, User, Product или Order). + (например, User, Product, Order) +3. `features` (фичи) — взаимодействия с пользователем, действия, которые несут бизнес-ценность для пользователя. + (например, SendComment, AddToCart, UsersSearch) +4. `widgets` (виджеты) — композиционный слой для соединения сущностей и фич в самостоятельные блоки + (например, IssuesList, UserProfile). +5. `pages` (страницы) — композиционный слой для сборки полноценных страниц из сущностей, фич и виджетов. +6. `processes` — сложные сценарии, покрывающие несколько страниц. + (например, авторизация) +7. `app` — настройки, стили и провайдеры для всего приложения. + +Затем есть слайсы, разделяющие код по предметной области. Они группируют логически связанные модули, что облегчает навигацию по кодовой базе. Слайсы не могут использовать другие слайсы на том же слое, что обеспечивает высокий уровень [_связности_][refs-wiki-cohesion] (cohesion) при низком уровне [_связанности_][refs-wiki-coupling] (coupling). + +В свою очередь, каждый слайс состоит из сегментов. Это маленькие модули, главная задача которых — разделить код внутри слайса по техническому назначению. Самые распространенные сегменты — `ui`, `model` (store, actions), `api` и `lib` (utils/hooks), но в вашем слайсе может не быть каких-то сегментов, могут быть другие, по вашему усмотрению. + +:::note + +В большинстве случаев [рекомендуется][ext-disc-api] располагать `api` и `config` только в shared-слое + +::: + +**Also, FSD have few core-concepts:** +- [Public API][refs-public-api] - each module must have a *declaration of its public API* at the top level - without access to internal structure of modules with isolation of implementation +- [Isolation][refs-isolation] (Low Coupling & High Cohesion) - the module should not *depend directly* on other modules of the same layer or overlying layers (to prevent implicit connections and side effects during development and refactoring) +- [Domain Driven][refs-needs-driven] - orientation *to the needs of the business and the user* with [app splitting][refs-splitting] by business domains + +### [`Public API`][refs-public-api] + +Каждый модуль должен иметь на верхнем уровне **декларацию своего публичного API** + +- Для подключения в другие модули, без нужды обращаться к внутренней структуре данного модуля +- Для изоляции деталей реализации от модулей-потребителей +- Также Public API должен защищать интерфейс модуля после рефакторинга - во избежание непредвиденных последствий + +### [`Isolation`][refs-isolation] + +Модуль не должен **зависеть напрямую** от других модулей того же слоя или вышележаших слоев + +- Концепция известна также как [Low Coupling & High Cohesion][refs-low-coupling] - для предотвращения неявных связей / сайд-эффектов при разработке и рефакторинге + +### [`Needs driven`][refs-needs-driven] + +Ориентирование **на потребности бизнеса и пользователя** + +- Включает в себя также разбиение структуры по бизнес-доменам *(["слоям"][refs-splitting-layers] и ["слайсам"][refs-splitting-slices])* + + +## Пример {#example} + +Рассмотрим приложение социальной сети. + +* `app/` содержит настройку роутера, глобальные хранилища и стили. +* `processes/` содержит часть аутентификации, отвечающую за чтение/запись токенов аутентификации. +* `pages/` содержит компоненты роутов на каждую страницу в приложении, преимущественно композирующие, по возможности, без собственной логики. + +В рамках этого приложения рассмотрим карточку поста в ленте новостей. + +* `widgets/` содержит "собранную" карточку поста, с содержимым и интерактивными кнопками, в которые вшиты запросы к бэкенду. +* `features/` содержит всю интерактивность карточки (например, кнопку лайка) и логику обработки этой интерактивности. +* `entities/` содержит скелет карточки со слотами под интерактивные элементы. Компонент, демонстрирующий автора поста, также находится в этой папке, но в другом слайсе. + +```sh +└── src/ + ├── app/ # Layer: Приложение + | # + ├── processes/ # Layer: Процессы (опционально) + | ├── {some-process}/ # Slice: (н-р процесс CartPayment) + | | ├── lib/ # Segment: Инфраструктурная-логика (helpers/utils) + | | └── model/ # Segment: Бизнес-логика + | ... # + ├── pages/ # Layer: Страницы + | ├── {some-page}/ # Slice: (н-р страница ProfilePage) + | | ├── lib/ # Segment: Инфраструктурная-логика (helpers/utils) + | | ├── model/ # Segment: Бизнес-логика + | | └── ui/ # Segment: UI-логика + | ... # + ├── widgets/ # Layer: Виджеты + | ├── {some-widget}/ # Slice: (н-р виджет Header) + | | ├── lib/ # Segment: Инфраструктурная-логика (helpers/utils) + | | ├── model/ # Segment: Бизнес-логика + | | └── ui/ # Segment: UI-логика + | ... # + ├── features/ # Layer: Фичи + | ├── {some-feature}/ # Slice: (н-р фича AuthByPhone) + | | ├── lib/ # Segment: Инфраструктурная-логика (helpers/utils) + | | ├── model/ # Segment: Бизнес-логика + | | └── ui/ # Segment: UI-логика + | ... # + ├── entities/ # Layer: Бизнес-сущности + | ├── {some-entity}/ # Slice: (н-р сущность User) + | | ├── lib/ # Segment: Инфраструктурная-логика (helpers/utils) + | | ├── model/ # Segment: Бизнес-логика + | | └── ui/ # Segment: UI-логика + | ... # + ├── shared/ # Layer: Переиспользуемые ресурсы + | ├── api/ # Segment: Логика запросов к API + | ├── config/ # Segment: Конфигурация приложения + | ├── lib/ # Segment: Инфраструктурная-логика приложения + | └── ui/ # Segment: UIKit приложения + | ... # + └── index.tsx/ # +``` + +### Преимущества {#advantages} + +- **Единообразие** + Код распределяется согласно области влияния (слой), предметной области (слайс) и техническому назначению (сегмент). + Благодаря этому архитектура стандартизируется и становится более простой для ознакомления. + +- **Контролируемое переиспользование логики** + Каждый компонент архитектуры имеет свое назначение и предсказуемый список зависимостей. + Благодаря этому сохраняется баланс между соблюдением принципа **DRY** и возможностью адаптировать модуль под разные цели. + +- **Устойчивость к изменениям и рефакторингу** + Один модуль не может использовать другой модуль, расположенный на том же слое или на слоях выше. + Благодаря этому приложение можно изолированно модифицировать под новые требования без непредвиденных последствий. + + +## Постепенное внедрение {#incremental-adoption} + +Сила FSD в _структурированной_ декомпозиции. В лучшей форме, FSD позволяет найти место для любой части кода почти однозначно. Однако, уровень декомпозиции — это параметр, и любая команда может подстроить его для оптимального баланса между легкостью внедрения и преимуществами. + +Предлагаем следующую стратегию для миграции существующей кодовой базы на FSD, проверенную опытом: + +1. Вырезать слои `app` и `shared`, чтобы иметь опору для последующих этапов. Эти слои получатся тонкими и простыми, пусть такими и остаются. + +2. Вынести весь интерфейс, связанный с бизнесом, распределить по виджетам и страницам, даже если в них пока что будут зависимости, нарушающие правила FSD. + +3. Постепенно наращивать степень декомпозиции, выделяя `features` и `entities`. Превращать страницы и виджеты из перегруженных логикой слоёв в чисто композиционные слои. + +Рекомендуется воздержаться от добавления новых крупных сущностей во время рефакторинга, а также рефакторинга по частям. + +## См. также {#see-also} + +- [(Раздел) Фундаментальные концепции методологии][refs-concepts] +- [(Раздел) Гайды и примеры по применению методологии][refs-guides] +- [(Статья) Про разбиение логики в приложении. Модуляризация][refs-splitting] + +[ext-disc-api]: https://github.com/feature-sliced/documentation/discussions/66 + +[refs-concepts]: /docs/concepts +[refs-public-api]: /docs/concepts/public-api +[refs-isolation]: /docs/concepts/cross-communication +[refs-needs-driven]: /docs/concepts/needs-driven + +[refs-splitting]: /docs/concepts/app-splitting + +[refs-guides]: /docs/guides +[refs-examples]: /examples +[refs-clean-architecture]: https://medium.com/codex/clean-architecture-for-dummies-df6561d42c94 diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/intro.mdx b/i18n/ru/docusaurus-plugin-content-docs/current/intro.mdx index 23b217c4fb..14d9a55a41 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/intro.mdx +++ b/i18n/ru/docusaurus-plugin-content-docs/current/intro.mdx @@ -1,93 +1,15 @@ --- sidebar_position: 1 +slug: / pagination_next: get-started/index --- -# 🔎 Введение - -OVERVIEW-ORIENTED +# Документация ![feature-sliced-banner](/img/banner.jpg) **Feature-Sliced Design** (FSD) — это архитектурная методология для проектирования frontend-приложений. Проще говоря, это свод правил и соглашений по организации кода. Главная цель методологии — сделать проект понятным и структурированным, особенно в условиях регулярного изменения требований бизнеса. -## Подходит ли это мне? {#is-it-right-for-me} - -FSD подходит для проектов и команд любого размера с некоторыми оговорками: - -- Эта методология исключительно для фронтенда. Если вы ищете архитектуру для бэкенда, обратите внимание на [Clean Architecture][refs-clean-architecture]. -- Если вы разрабатываете очень простое приложение из одной странички на FSD, преимущества методологии вряд ли понадобятся, а вот разработка может замедлиться. Однако, FSD помогает стандартизированно мыслить о фронтенд-приложениях, так что смело используйте даже на маленьких проектах, если знаете, для чего она вам. -- Огромное приложение, соизмеримое с админ-панелью Google Cloud, потребует специализированной архитектуры. FSD в данном случае может выступать в качестве отправной точки. - -Методология не привязана к конкретному языку программирования, UI-фреймворку или менеджеру состояния — подойдет любой (см. [примеры использования][refs-examples]). - -Если у вас уже есть проект, не переживайте — FSD можно внедрять постепенно. Главный вопрос, который стоит задать команде: "**Eсть ли боль** при разработке проекта?" Если боли нет, возможно, переход делать не стоит. - -## Краткий обзор {#overview} - -Проект на FSD состоит из _слоев_ (layers), каждый слой состоит из _слайсов_ (slices) и каждый слайс состоит из _сегментов_ (segments). - -![themed--scheme](/img/visual_schema.jpg) - -Слои стандартизированы во всех проектах и расположены вертикально. Модули на одном слое могут взаимодействовать лишь с модулями, находящимися на слоях строго ниже. На данный момент слоев семь (снизу вверх): - -1. **Shared** — переиспользуемый код, не имеющий отношения к специфике приложения/бизнеса. -2. **Entities** (сущности) — бизнес-сущности (например, User, Product или Order). -3. **Features** (фичи) — взаимодействия с пользователем, действия, которые несут бизнес-ценность для пользователя. -4. **Widgets** (виджеты) — композиционный слой для соединения сущностей и фич в самостоятельные блоки. -5. **Pages** (страницы) — композиционный слой для сборки полноценных страниц из сущностей, фич и виджетов. -6. **Processes** — сложные сценарии, покрывающие несколько страниц (например, аутентификация). -7. **App** — настройки, стили и провайдеры для всего приложения. - -Затем есть слайсы, разделяющие код по предметной области. Они группируют логически связанные модули, что облегчает навигацию по кодовой базе. Слайсы не могут использовать другие слайсы на том же слое, что обеспечивает высокий уровень [_связности_][refs-wiki-cohesion] (cohesion) при низком уровне [_связанности_][refs-wiki-coupling] (coupling). - -В свою очередь, каждый слайс состоит из сегментов. Это маленькие модули, главная задача которых — разделить код внутри слайса по техническому назначению. Самые распространенные сегменты — `ui`, `model`, `api` и `lib`, но в вашем слайсе может не быть каких-то сегментов, могут быть другие, по вашему усмотрению. - -### Пример декомпозиции {#decomposition-example} - -Рассмотрим приложение социальной сети. - -* `app/` содержит настройку роутера, глобальные хранилища и стили. -* `processes/` содержит часть аутентификации, отвечающую за чтение/запись токенов аутентификации. -* `pages/` содержит компоненты роутов на каждую страницу в приложении, преимущественно композирующие, по возможности, без собственной логики. - -В рамках этого приложения рассмотрим карточку поста в ленте новостей. - -* `widgets/` содержит "собранную" карточку поста, с содержимым и интерактивными кнопками, в которые вшиты запросы к бэкенду. -* `features/` содержит всю интерактивность карточки (например, кнопку лайка) и логику обработки этой интерактивности. -* `entities/` содержит скелет карточки со слотами под интерактивные элементы. Компонент, демонстрирующий автора поста, также находится в этой папке, но в другом слайсе. - -### Преимущества {#advantages} - -- **Единообразие** - Код распределяется согласно области влияния (слой), предметной области (слайс) и техническому назначению (сегмент). - Благодаря этому архитектура стандартизируется и становится более простой для ознакомления. - -- **Контролируемое переиспользование логики** - Каждый компонент архитектуры имеет свое назначение и предсказуемый список зависимостей. - Благодаря этому сохраняется баланс между соблюдением принципа **DRY** и возможностью адаптировать модуль под разные цели. - -- **Устойчивость к изменениям и рефакторингу** - Один модуль не может использовать другой модуль, расположенный на том же слое или на слоях выше. - Благодаря этому приложение можно изолированно модифицировать под новые требования без непредвиденных последствий. - - -## Постепенное внедрение {#incremental-adoption} - -Сила FSD в _структурированной_ декомпозиции. В лучшей форме, FSD позволяет найти место для любой части кода почти однозначно. Однако, уровень декомпозиции — это параметр, и любая команда может подстроить его для оптимального баланса между легкостью внедрения и преимуществами. - -Предлагаем следующую стратегию для миграции существующей кодовой базы на FSD, проверенную опытом: - -1. Вырезать слои `app` и `shared`, чтобы иметь опору для последующих этапов. Эти слои получатся тонкими и простыми, пусть такими и остаются. - -2. Вынести весь интерфейс, связанный с бизнесом, распределить по виджетам и страницам, даже если в них пока что будут зависимости, нарушающие правила FSD. - -3. Постепенно наращивать степень декомпозиции, выделяя `features` и `entities`. Превращать страницы и виджеты из перегруженных логикой слоёв в чисто композиционные слои. - -Рекомендуется воздержаться от добавления новых крупных сущностей во время рефакторинга, а также рефакторинга по частям. - -## Что дальше? {#whats-next} - import Row from "@site/src/shared/ui/row/tmpl.mdx" import { RocketOutlined, ThunderboltOutlined, FundViewOutlined } from "@ant-design/icons"; import Link from "@docusaurus/Link"; @@ -140,9 +62,3 @@ import Link from "@docusaurus/Link"; to="/examples" Icon={"🛠"} /> - -[refs-clean-architecture]: https://medium.com/codex/clean-architecture-for-dummies-df6561d42c94 -[refs-wiki-cohesion]: https://ru.wikipedia.org/wiki/%D0%A1%D0%B2%D1%8F%D0%B7%D0%BD%D0%BE%D1%81%D1%82%D1%8C_(%D0%BF%D1%80%D0%BE%D0%B3%D1%80%D0%B0%D0%BC%D0%BC%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5) -[refs-wiki-coupling]: https://ru.wikipedia.org/wiki/%D0%97%D0%B0%D1%86%D0%B5%D0%BF%D0%BB%D0%B5%D0%BD%D0%B8%D0%B5_(%D0%BF%D1%80%D0%BE%D0%B3%D1%80%D0%B0%D0%BC%D0%BC%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5) - -[refs-examples]: /examples diff --git a/i18n/ru/docusaurus-theme-classic/footer.json b/i18n/ru/docusaurus-theme-classic/footer.json index 818084af3f..ac656a8817 100644 --- a/i18n/ru/docusaurus-theme-classic/footer.json +++ b/i18n/ru/docusaurus-theme-classic/footer.json @@ -13,7 +13,7 @@ }, "link.item.label.Documentation": { "message": "Документация", - "description": "The label of footer link with label=Документация linking to /docs/intro" + "description": "The label of footer link with label=Документация linking to /docs" }, "link.item.label.Discussions": { "message": "Обсуждения", diff --git a/src/app/index.scss b/src/app/index.scss index c2de09ac63..aee867e5e0 100644 --- a/src/app/index.scss +++ b/src/app/index.scss @@ -117,6 +117,13 @@ iframe { border-radius: 16px; } +mark { + padding: 2px; + color: #ffffff; + background-color: var(--ifm-color-primary); + border-radius: 4px; +} + /* media */ /* TODO: connect as file */ @@ -237,7 +244,7 @@ a[download] { } } - &__logo { - margin-right: 0; - } + // &__logo { + // margin-right: 0; + // } } From 187bec716d3e6c4bc3a06892546425b6ec84d35f Mon Sep 17 00:00:00 2001 From: Ilya Azin Date: Sat, 17 Sep 2022 14:08:42 +0300 Subject: [PATCH 03/10] feat(overview): simplify navbar and refine announcementBar DISCOVERY-335 --- docusaurus.config.js | 65 ++++++++++++-------------------------------- routes.config.js | 60 +++++----------------------------------- src/app/index.scss | 6 ++++ 3 files changed, 31 insertions(+), 100 deletions(-) diff --git a/docusaurus.config.js b/docusaurus.config.js index 552584ebbe..541fc7fed9 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -1,6 +1,6 @@ require("dotenv").config(); const path = require("path"); -const { REDIRECTS, SECTIONS, LEGACY_ROUTES } = require("./routes.config"); +const { REDIRECTS, LEGACY_ROUTES } = require("./routes.config"); const DOMAIN = "https://feature-sliced.design/"; const GITHUB_ORG = "https://github.com/feature-sliced"; @@ -32,60 +32,23 @@ const navbar = { items: [ // left { - type: "dropdown", label: "📖 Docs", + to: "/docs", position: "left", - items: [ - { - label: "🔎 Intro", - to: SECTIONS.INTRO.fullPath, - activeBasePath: SECTIONS.INTRO.fullPath, - }, - { - label: "🚀 Get Started", - to: SECTIONS.GET_STARTED.shortPath, - activeBasePath: SECTIONS.GET_STARTED.shortPath, - }, - { - label: "🎯 Guides", - to: SECTIONS.GUIDES.shortPath, - activeBasePath: SECTIONS.GUIDES.shortPath, - }, - { - label: "🧩 Concepts", - to: SECTIONS.CONCEPTS.shortPath, - activeBasePath: SECTIONS.CONCEPTS.shortPath, - }, - { - label: "📚 Reference", - to: SECTIONS.REFERENCE.shortPath, - activeBasePath: SECTIONS.REFERENCE.shortPath, - }, - { - label: "🍰 About", - to: SECTIONS.ABOUT.shortPath, - activeBasePath: SECTIONS.ABOUT.shortPath, - }, - { - label: "💫 Community", - to: SECTIONS.COMMUNITY.fullPath, - activeBasePath: SECTIONS.COMMUNITY.fullPath, - }, - ], }, { - label: "🛠 Examples", - to: SECTIONS.EXAMPLES.fullPath, + label: "💫 Community", + to: "/community", position: "left", }, { - label: "❔ Help", - to: "/nav", + label: "📝 Blog", + to: "/blog", position: "left", }, { - label: "📝 Blog", - to: "/blog", + label: "🛠 Examples", + to: "/examples", position: "left", }, // right @@ -145,7 +108,9 @@ const footer = { { title: "Specs", items: [ - { label: "Documentation", to: "/docs/intro" }, + { label: "Documentation", to: "/docs" }, + { label: "Community", to: "/community" }, + { label: "Help", to: "/nav" }, { label: "Discussions", to: `${GITHUB_DOCS}/discussions` }, ], }, @@ -297,6 +262,8 @@ const algolia = { // contextualSearch: true, }; +const NBSP = " "; + /** @type {Config["themeConfig"]["announcementBar"]} */ const announcementBar = { id: "bar", // Any value that will identify this message. @@ -307,7 +274,11 @@ const announcementBar = { // content: `📚 Documentation refinements are in progress. Stay tuned for updates and share your feedback`, // backgroundColor: "#5c9cb5", // As primary theme // backgroundColor: "#0367d2", - content: `🍰 We're rebranding!  |  ☮️ Stop the war in Ukraine! #NoWar`, // #nowar + content: [ + `🍰 We're rebranding!`, + `❔Help`, + `☮️ Stop the war in Ukraine! #NoWar`, // #nowar + ].join(`${NBSP + NBSP}|${NBSP + NBSP}`), backgroundColor: "#000000", // #nowar textColor: "#fff", // Defaults to `#000`. isCloseable: false, // Defaults to `true`. diff --git a/routes.config.js b/routes.config.js index ba6d8745dd..43cf13d2f1 100644 --- a/routes.config.js +++ b/routes.config.js @@ -1,45 +1,8 @@ // Custom "not-docusaurus-related" config for routes setup // @see https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-client-redirects -// FIXME: Clean up urls format (with new index-pages) +// FIXME: move to root and remove "docs" redundant prefix later const SECTIONS = { - INTRO: { - shortPath: "/docs", - fullPath: "/docs/intro", - }, - GET_STARTED: { - shortPath: "/docs/get-started", - fullPath: "/docs/get-started", - }, - CONCEPTS: { - shortPath: "/docs/concepts", - fullPath: "/docs/concepts", - }, - GUIDES: { - shortPath: "/docs/guides", - fullPath: "/docs/guides", - }, - REFERENCE: { - shortPath: "/docs/reference", - fullPath: "/docs/reference", - }, - LAYERS: { - shortPath: "/docs/reference/layers", - fullPath: "/docs/reference/layers/overview", - }, - ABOUT: { - shortPath: "/docs/about", - fullPath: "/docs/about", - }, - COMMUNITY: { - shortPath: "/docs/community", - fullPath: "/community", - }, - EXAMPLES: { - shortPath: "/examples", - fullPath: "/examples", - }, - // FIXME: Temp, use later root "/" folders without "docs" redundant prefix BRANDING: { shortPath: "/branding", fullPath: "/docs/branding", @@ -55,11 +18,6 @@ const LEGACY_ROUTES = [ group: "🚀 Get Started", details: "Simplified and merged", children: [ - { - title: "Overview", - from: "/docs/get-started/overview", - to: "/docs/intro", - }, { title: "QuickStart", from: "/docs/get-started/tutorial/quick-start", @@ -253,13 +211,10 @@ const LEGACY_ROUTES_REDIRECTS = LEGACY_ROUTES.reduce((acc, group) => { // FIXME: temp, resolve later // @returns { from, to }[] -const SECTIONS_REDIRECTS = Object.values(SECTIONS) - // Custom filtering - .filter(({ shortPath, fullPath }) => shortPath !== fullPath) - .map(({ shortPath, fullPath }) => ({ - from: shortPath, - to: fullPath, - })); +const SECTIONS_REDIRECTS = Object.values(SECTIONS).map(({ shortPath, fullPath }) => ({ + from: shortPath, + to: fullPath, +})); // !!! FIXME: refactor later! const _TOTAL_ROUTES = [ @@ -296,7 +251,7 @@ const _TOTAL_ROUTES = [ "/docs/concepts/public-api", "/docs/concepts/signals", "/docs/get-started", - "/docs/get-started/basics", + "/docs/get-started/overview", "/docs/get-started/cheatsheet", "/docs/get-started/faq", "/docs/get-started/quick-start", @@ -319,7 +274,7 @@ const _TOTAL_ROUTES = [ "/docs/guides/migration/from-legacy", "/docs/guides/migration/from-v1", "/docs/guides/tech/with-nextjs", - "/docs/intro", + "/docs/", "/docs/privacy", "/docs/reference", "/docs/reference/glossary", @@ -343,7 +298,6 @@ const I18N_REDIRECTS = _TOTAL_ROUTES.map((route) => ({ const REDIRECTS = [...SECTIONS_REDIRECTS, ...LEGACY_ROUTES_REDIRECTS, ...I18N_REDIRECTS]; module.exports = { - SECTIONS, LEGACY_ROUTES, REDIRECTS, }; diff --git a/src/app/index.scss b/src/app/index.scss index aee867e5e0..655353751e 100644 --- a/src/app/index.scss +++ b/src/app/index.scss @@ -189,6 +189,7 @@ mark { } /* I love adaptive styles... */ +/* FIXME: add unified adaptive breakpoints */ @media (max-width: 1080px) { .navbar__item { padding: var(--ifm-navbar-item-padding-vertical) 0.25rem; @@ -200,6 +201,11 @@ mark { display: block; } } +@media (max-width: 600px) { + [role="banner"] { + font-size: 1.0rem; // #nowar + } +} a[download] { transition: 0.25s; From 48dcd42aed96a6dd2f6ad2f6a3d495368d1f39f6 Mon Sep 17 00:00:00 2001 From: Ilya Azin Date: Sat, 17 Sep 2022 14:35:17 +0300 Subject: [PATCH 04/10] fix(overview): [Review] clean up Overview article (en, ru) DISCOVERY-335 --- .../current/get-started/overview.md | 85 ++------------ .../current/get-started/overview.md | 106 ++---------------- routes.config.js | 4 + src/app/index.scss | 2 +- src/app/theme.scss | 1 + 5 files changed, 24 insertions(+), 174 deletions(-) diff --git a/i18n/en/docusaurus-plugin-content-docs/current/get-started/overview.md b/i18n/en/docusaurus-plugin-content-docs/current/get-started/overview.md index 3584370eb0..ee6b3fd051 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/get-started/overview.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/get-started/overview.md @@ -4,14 +4,6 @@ sidebar_position: 1 # Overview -:::caution - -Only basic information on the methodology is presented here - -For a more competent application, it is worth getting acquainted with each concept in more detail in the corresponding section of the documentation - -::: - ## Is it right for me? FSD can be implemented in projects and teams of any size, but there are a few things to keep in mind: @@ -22,7 +14,7 @@ FSD can be implemented in projects and teams of any size, but there are a few th FSD doesn't enforce a particular programming language, UI framework or state manager — bring your own or see some [examples][refs-examples]. -If you have an existing project, fear not — FSD can be adopted incrementally. Just make sure that your team is **in pain** from the current architecture, otherwise a switch might not be worth it. +If you have an existing project, fear not — FSD can be adopted incrementally. Just make sure that your team is **in pain** from the current architecture, otherwise a switch might not be worth it. For migration guidance, see the [Migration section][refs-migration]. ## Basics @@ -30,7 +22,7 @@ In FSD, a [project consists][refs-splitting] of layers, each layer ![themed--scheme](/img/visual_schema.jpg) -The layers are standardized across all projects and vertically arranged. Modules on one layer can only interact with modules from the layers strictly below. There are currently seven of them (bottom to top): +The **layers** are standardized across all projects and vertically arranged. Modules on one layer can only interact with modules from the layers strictly below. There are currently seven of them (bottom to top): 1. `shared` — reusable functionality, detached from the specifics of the project/business. (e.g. UIKit, libs, API) @@ -46,9 +38,9 @@ The layers are standardized across all projects and vertically arra 7. `app` — app-wide settings, styles and providers. -Then there are slices, which partition the code by business domain. This makes your codebase easy to navigate by keeping logically related modules close together. Slices cannot use other slices on the same layer, and that helps with high cohesion and low coupling. +Then there are **slices**, which partition the code by business domain. This makes your codebase easy to navigate by keeping logically related modules close together. Slices cannot use other slices on the same layer, and that helps with high cohesion and low coupling. -Each slice, in turn, consists of segments. These are tiny modules that are meant to help with separating code within a slice by its technical purpose. The most common segments are `ui`, `model` (store, actions), `api` and `lib` (utils/hooks), but you can omit some or add more, as you see fit. +Each slice, in turn, consists of **segments**. These are tiny modules that are meant to help with separating code within a slice by its technical purpose. The most common segments are `ui`, `model` (store, actions), `api` and `lib` (utils/hooks), but you can omit some or add more, as you see fit. :::note @@ -56,11 +48,6 @@ In most cases, [it is recommended][ext-disc-api] to place `api` and `config` onl ::: -**Also, FSD have few core-concepts:** -- [Public API][refs-public-api] - each module must have a *declaration of its public API* at the top level - without access to internal structure of modules with isolation of implementation -- [Isolation][refs-isolation] (Low Coupling & High Cohesion) - the module should not *depend directly* on other modules of the same layer or overlying layers (to prevent implicit connections and side effects during development and refactoring) -- [Domain Driven][refs-needs-driven] - orientation *to the needs of the business and the user* with [app splitting][refs-splitting] by business domains - ## Example Let's consider a social network application. @@ -75,49 +62,6 @@ Within that application, let's consider a post card in a news feed. * `features/` contains the interactivity of the card (e.g., like button) and the logic of processing those interactions. * `entities/` contains the shell of the card with slots for content and the interactive elements. The tile representing the post author is also here, but in a different slice. - -```sh -└── src/ - ├── app/ # Layer: Application - | # - ├── processes/ # Layer: Processes (optional) - | ├── {some-process}/ # Slice: (e.g. CartPayment process) - | | ├── lib/ # Segment: Utility logic (utils/hooks) - | | └── model/ # Segment: Business Logic - | ... # - ├── pages/ # Layer: Pages - | ├── {some-page}/ # Slice: (e.g. ProfilePage page) - | | ├── lib/ # Segment: Utility logic (utils/hooks) - | | ├── model/ # Segment: Business Logic - | | └── ui/ # Segment: UI logic - | ... # - ├── widgets/ # Layer: Widgets - | ├── {some-widget}/ # Slice: (e.g. Header widget) - | | ├── lib/ # Segment: Utility logic (utils/hooks) - | | ├── model/ # Segment: Business Logic - | | └── ui/ # Segment: UI logic - | ... # - ├── features/ # Layer: Features - | ├── {some-feature}/ # Slice: (e.g. AuthByPhone feature) - | | ├── lib/ # Segment: Utility logic (utils/hooks) - | | ├── model/ # Segment: Business Logic - | | └── ui/ # Segment: UI logic - | ... # - ├── entities/ # Layer: Business Entities - | ├── {some-entity}/ # Slice: (e.g. entity User) - | | ├── lib/ # Segment: Utility logic (utils/hooks) - | | ├── model/ # Segment: Business Logic - | | └── ui/ # Segment: UI logic - | ... # - ├── shared/ # Layer: Reused resources - | ├── api/ # Segment: Logic of API requests - | ├── config/ # Segment: Application configuration - | ├── lib/ # Segment: General utility logic - | └── ui/ # Segment: UIKit of the application - | ... # - └── index.tsx/ # -``` - ## Advantages - **Uniformity** @@ -132,6 +76,8 @@ Within that application, let's consider a post card in a news feed. A module on a particular layer cannot use other modules on the same layer, or the layers above. This enables isolated modifications without unforeseen consequences. +- **Orientation to business and users needs** + App splitting by business domains help to deeper understand, structure and discovery project features. ## Incremental adoption @@ -147,21 +93,8 @@ Here's a proposed strategy to migrate an existing codebase to FSD, based on expe It's advised to refrain from adding new large entities while refactoring or refactoring only certain parts of the project. -## See also - -- [(Section) Fundamental concepts of the methodology][refs-concepts] -- [(Section) Guides and examples on the application of the methodology][refs-guides] -- [(Article) About splitting the logic in the application. Modularization][refs-splitting] - +[refs-clean-architecture]: https://medium.com/codex/clean-architecture-for-dummies-df6561d42c94 [ext-disc-api]: https://github.com/feature-sliced/documentation/discussions/66 - -[refs-concepts]: /docs/concepts -[refs-public-api]: /docs/concepts/public-api -[refs-isolation]: /docs/concepts/cross-communication -[refs-needs-driven]: /docs/concepts/needs-driven - -[refs-splitting]: /docs/concepts/app-splitting - -[refs-guides]: /docs/guides [refs-examples]: /examples -[refs-clean-architecture]: https://medium.com/codex/clean-architecture-for-dummies-df6561d42c94 +[refs-migration]: /docs/guides/migration +[refs-splitting]: /docs/concepts/app-splitting diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/get-started/overview.md b/i18n/ru/docusaurus-plugin-content-docs/current/get-started/overview.md index e7125d0405..cb601f8bbd 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/get-started/overview.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/get-started/overview.md @@ -4,15 +4,6 @@ sidebar_position: 1 # Основы {#basics} -:::caution Предупреждение - -Здесь представлена лишь основная информация по методологии - -Для более грамотного применения, стоит ознакомится детальней с каждым понятием в соответствующем разделе документации - -::: - - ## Подходит ли это мне? {#is-it-right-for-me} FSD подходит для проектов и команд любого размера с некоторыми оговорками: @@ -23,7 +14,7 @@ FSD подходит для проектов и команд любого раз Методология не привязана к конкретному языку программирования, UI-фреймворку или менеджеру состояния — подойдет любой (см. [примеры использования][refs-examples]). -Если у вас уже есть проект, не переживайте — FSD можно внедрять постепенно. Главный вопрос, который стоит задать команде: "**Eсть ли боль** при разработке проекта?" Если боли нет, возможно, переход делать не стоит. +Если у вас уже есть проект, не переживайте — FSD можно внедрять постепенно. Главный вопрос, который стоит задать команде: "**Eсть ли боль** при разработке проекта?" Если боли нет, возможно, переход делать не стоит. Руководство по миграции см. в разделе [Миграция][refs-migration]. ## Основы {#basics} @@ -32,7 +23,7 @@ FSD подходит для проектов и команд любого раз ![themed--scheme](/img/visual_schema.jpg) -Слои стандартизированы во всех проектах и расположены вертикально. Модули на одном слое могут взаимодействовать лишь с модулями, находящимися на слоях строго ниже. На данный момент слоев семь (снизу вверх): +**Слои** стандартизированы во всех проектах и расположены вертикально. Модули на одном слое могут взаимодействовать лишь с модулями, находящимися на слоях строго ниже. На данный момент слоев семь (снизу вверх): 1. `shared` — переиспользуемый код, не имеющий отношения к специфике приложения/бизнеса. (например, UIKit, libs, API) @@ -47,9 +38,9 @@ FSD подходит для проектов и команд любого раз (например, авторизация) 7. `app` — настройки, стили и провайдеры для всего приложения. -Затем есть слайсы, разделяющие код по предметной области. Они группируют логически связанные модули, что облегчает навигацию по кодовой базе. Слайсы не могут использовать другие слайсы на том же слое, что обеспечивает высокий уровень [_связности_][refs-wiki-cohesion] (cohesion) при низком уровне [_связанности_][refs-wiki-coupling] (coupling). +Затем есть **слайсы**, разделяющие код по предметной области. Они группируют логически связанные модули, что облегчает навигацию по кодовой базе. Слайсы не могут использовать другие слайсы на том же слое, что обеспечивает высокий уровень [_связности_][refs-wiki-cohesion] (cohesion) при низком уровне [_связанности_][refs-wiki-coupling] (coupling). -В свою очередь, каждый слайс состоит из сегментов. Это маленькие модули, главная задача которых — разделить код внутри слайса по техническому назначению. Самые распространенные сегменты — `ui`, `model` (store, actions), `api` и `lib` (utils/hooks), но в вашем слайсе может не быть каких-то сегментов, могут быть другие, по вашему усмотрению. +В свою очередь, каждый слайс состоит из **сегментов**. Это маленькие модули, главная задача которых — разделить код внутри слайса по техническому назначению. Самые распространенные сегменты — `ui`, `model` (store, actions), `api` и `lib` (utils/hooks), но в вашем слайсе может не быть каких-то сегментов, могут быть другие, по вашему усмотрению. :::note @@ -57,32 +48,6 @@ FSD подходит для проектов и команд любого раз ::: -**Also, FSD have few core-concepts:** -- [Public API][refs-public-api] - each module must have a *declaration of its public API* at the top level - without access to internal structure of modules with isolation of implementation -- [Isolation][refs-isolation] (Low Coupling & High Cohesion) - the module should not *depend directly* on other modules of the same layer or overlying layers (to prevent implicit connections and side effects during development and refactoring) -- [Domain Driven][refs-needs-driven] - orientation *to the needs of the business and the user* with [app splitting][refs-splitting] by business domains - -### [`Public API`][refs-public-api] - -Каждый модуль должен иметь на верхнем уровне **декларацию своего публичного API** - -- Для подключения в другие модули, без нужды обращаться к внутренней структуре данного модуля -- Для изоляции деталей реализации от модулей-потребителей -- Также Public API должен защищать интерфейс модуля после рефакторинга - во избежание непредвиденных последствий - -### [`Isolation`][refs-isolation] - -Модуль не должен **зависеть напрямую** от других модулей того же слоя или вышележаших слоев - -- Концепция известна также как [Low Coupling & High Cohesion][refs-low-coupling] - для предотвращения неявных связей / сайд-эффектов при разработке и рефакторинге - -### [`Needs driven`][refs-needs-driven] - -Ориентирование **на потребности бизнеса и пользователя** - -- Включает в себя также разбиение структуры по бизнес-доменам *(["слоям"][refs-splitting-layers] и ["слайсам"][refs-splitting-slices])* - - ## Пример {#example} Рассмотрим приложение социальной сети. @@ -97,48 +62,6 @@ FSD подходит для проектов и команд любого раз * `features/` содержит всю интерактивность карточки (например, кнопку лайка) и логику обработки этой интерактивности. * `entities/` содержит скелет карточки со слотами под интерактивные элементы. Компонент, демонстрирующий автора поста, также находится в этой папке, но в другом слайсе. -```sh -└── src/ - ├── app/ # Layer: Приложение - | # - ├── processes/ # Layer: Процессы (опционально) - | ├── {some-process}/ # Slice: (н-р процесс CartPayment) - | | ├── lib/ # Segment: Инфраструктурная-логика (helpers/utils) - | | └── model/ # Segment: Бизнес-логика - | ... # - ├── pages/ # Layer: Страницы - | ├── {some-page}/ # Slice: (н-р страница ProfilePage) - | | ├── lib/ # Segment: Инфраструктурная-логика (helpers/utils) - | | ├── model/ # Segment: Бизнес-логика - | | └── ui/ # Segment: UI-логика - | ... # - ├── widgets/ # Layer: Виджеты - | ├── {some-widget}/ # Slice: (н-р виджет Header) - | | ├── lib/ # Segment: Инфраструктурная-логика (helpers/utils) - | | ├── model/ # Segment: Бизнес-логика - | | └── ui/ # Segment: UI-логика - | ... # - ├── features/ # Layer: Фичи - | ├── {some-feature}/ # Slice: (н-р фича AuthByPhone) - | | ├── lib/ # Segment: Инфраструктурная-логика (helpers/utils) - | | ├── model/ # Segment: Бизнес-логика - | | └── ui/ # Segment: UI-логика - | ... # - ├── entities/ # Layer: Бизнес-сущности - | ├── {some-entity}/ # Slice: (н-р сущность User) - | | ├── lib/ # Segment: Инфраструктурная-логика (helpers/utils) - | | ├── model/ # Segment: Бизнес-логика - | | └── ui/ # Segment: UI-логика - | ... # - ├── shared/ # Layer: Переиспользуемые ресурсы - | ├── api/ # Segment: Логика запросов к API - | ├── config/ # Segment: Конфигурация приложения - | ├── lib/ # Segment: Инфраструктурная-логика приложения - | └── ui/ # Segment: UIKit приложения - | ... # - └── index.tsx/ # -``` - ### Преимущества {#advantages} - **Единообразие** @@ -153,6 +76,8 @@ FSD подходит для проектов и команд любого раз Один модуль не может использовать другой модуль, расположенный на том же слое или на слоях выше. Благодаря этому приложение можно изолированно модифицировать под новые требования без непредвиденных последствий. +- **Ориентированность на потребности бизнеса и пользователей** + Разбиение приложение по бизнес-доменам помогает глубже понять, структурировать и находить фичи проекта. ## Постепенное внедрение {#incremental-adoption} @@ -168,21 +93,8 @@ FSD подходит для проектов и команд любого раз Рекомендуется воздержаться от добавления новых крупных сущностей во время рефакторинга, а также рефакторинга по частям. -## См. также {#see-also} - -- [(Раздел) Фундаментальные концепции методологии][refs-concepts] -- [(Раздел) Гайды и примеры по применению методологии][refs-guides] -- [(Статья) Про разбиение логики в приложении. Модуляризация][refs-splitting] - +[refs-clean-architecture]: https://medium.com/codex/clean-architecture-for-dummies-df6561d42c94 [ext-disc-api]: https://github.com/feature-sliced/documentation/discussions/66 - -[refs-concepts]: /docs/concepts -[refs-public-api]: /docs/concepts/public-api -[refs-isolation]: /docs/concepts/cross-communication -[refs-needs-driven]: /docs/concepts/needs-driven - -[refs-splitting]: /docs/concepts/app-splitting - -[refs-guides]: /docs/guides [refs-examples]: /examples -[refs-clean-architecture]: https://medium.com/codex/clean-architecture-for-dummies-df6561d42c94 +[refs-migration]: /docs/guides/migration +[refs-splitting]: /docs/concepts/app-splitting diff --git a/routes.config.js b/routes.config.js index 43cf13d2f1..5e308429e2 100644 --- a/routes.config.js +++ b/routes.config.js @@ -7,6 +7,10 @@ const SECTIONS = { shortPath: "/branding", fullPath: "/docs/branding", }, + MIGRATION: { + shortPath: "//docs/guides/migration", + fullPath: "/docs/guides/migration/from-legacy", + }, }; /** diff --git a/src/app/index.scss b/src/app/index.scss index 655353751e..0de919e28b 100644 --- a/src/app/index.scss +++ b/src/app/index.scss @@ -120,7 +120,7 @@ iframe { mark { padding: 2px; color: #ffffff; - background-color: var(--ifm-color-primary); + background-color: var(--ifm-color-primary-neutral); border-radius: 4px; } diff --git a/src/app/theme.scss b/src/app/theme.scss index ddd429ab8e..84a2da7ec3 100644 --- a/src/app/theme.scss +++ b/src/app/theme.scss @@ -39,6 +39,7 @@ --ifm-color-primary-lightest: #6b9ee1; --ifm-color-primary-grad1: #29bedc; --ifm-color-primary-grad2: #517aed; + --ifm-color-primary-neutral: #4a7ec2c6; --ifm-font-family-base: 'Ubuntu', system-ui, -apple-system, segoe ui, roboto, ubuntu, cantarell, noto sans, sans-serif, blinkmacsystemfont, 'Segoe UI', helvetica, arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; --ifm-heading-font-family: 'Overpass', var(--ifm-font-family-base); } From 5e85424f9c1607f3a242c3ada5adca7a8cc52a15 Mon Sep 17 00:00:00 2001 From: Ilya Azin Date: Sat, 17 Sep 2022 14:41:06 +0300 Subject: [PATCH 05/10] refactor(index-page): rename NavCard component DISCOVERY-335 --- .../community/index.mdx | 10 +++++----- .../current/about/index.mdx | 6 +++--- .../current/concepts/index.mdx | 12 ++++++------ .../current/get-started/index.mdx | 8 ++++---- .../current/guides/examples/index.mdx | 8 ++++---- .../current/guides/index.mdx | 8 ++++---- .../current/intro.mdx | 16 ++++++++-------- .../current/reference/index.mdx | 8 ++++---- .../community/index.mdx | 10 +++++----- .../current/about/index.mdx | 6 +++--- .../current/concepts/index.mdx | 12 ++++++------ .../current/get-started/index.mdx | 8 ++++---- .../current/guides/examples/index.mdx | 8 ++++---- .../current/guides/index.mdx | 8 ++++---- .../current/intro.mdx | 16 ++++++++-------- .../current/reference/index.mdx | 8 ++++---- src/pages/nav/index.jsx | 4 ++-- src/shared/ui/{row => nav-card}/index.jsx | 6 +++--- .../ui/{row => nav-card}/styles.module.scss | 0 src/shared/ui/nav-card/tmpl.mdx | 3 +++ src/shared/ui/row/tmpl.mdx | 3 --- 21 files changed, 84 insertions(+), 84 deletions(-) rename src/shared/ui/{row => nav-card}/index.jsx (94%) rename src/shared/ui/{row => nav-card}/styles.module.scss (100%) create mode 100644 src/shared/ui/nav-card/tmpl.mdx delete mode 100644 src/shared/ui/row/tmpl.mdx diff --git a/i18n/en/docusaurus-plugin-content-docs/community/index.mdx b/i18n/en/docusaurus-plugin-content-docs/community/index.mdx index ddc6c3aa36..0e8dc5f912 100644 --- a/i18n/en/docusaurus-plugin-content-docs/community/index.mdx +++ b/i18n/en/docusaurus-plugin-content-docs/community/index.mdx @@ -15,28 +15,28 @@ Community resources, additional materials ## Main -import Row from "@site/src/shared/ui/row/tmpl.mdx" +import NavCard from "@site/src/shared/ui/nav-card/tmpl.mdx" import { StarOutlined, SearchOutlined, TeamOutlined, VerifiedOutlined } from "@ant-design/icons"; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - { @@ -37,7 +37,7 @@ const GroupItems = () => {

⚡️ {routesBatch.details}

{routesBatch.children.map((route) => ( - { +export const NavCard = (props) => { const { title, description, to, Icon, tags, className, disabled } = props; const handleClick = useCallback(() => { ga.sendEvent({ @@ -49,4 +49,4 @@ const RowIcon = ({ Icon }) => { return ; }; -export default Row; +export default NavCard; diff --git a/src/shared/ui/row/styles.module.scss b/src/shared/ui/nav-card/styles.module.scss similarity index 100% rename from src/shared/ui/row/styles.module.scss rename to src/shared/ui/nav-card/styles.module.scss diff --git a/src/shared/ui/nav-card/tmpl.mdx b/src/shared/ui/nav-card/tmpl.mdx new file mode 100644 index 0000000000..855bd81e7f --- /dev/null +++ b/src/shared/ui/nav-card/tmpl.mdx @@ -0,0 +1,3 @@ +import NavCard from "./index.jsx"; + + diff --git a/src/shared/ui/row/tmpl.mdx b/src/shared/ui/row/tmpl.mdx deleted file mode 100644 index 59e2f7bcf4..0000000000 --- a/src/shared/ui/row/tmpl.mdx +++ /dev/null @@ -1,3 +0,0 @@ -import Row from "./index.jsx"; - - From 522b19dd4fced5f5c6df5ec78eb106e462c5e705 Mon Sep 17 00:00:00 2001 From: Ilya Azin Date: Mon, 19 Sep 2022 11:13:35 +0300 Subject: [PATCH 06/10] feat(index-page): add themes for NavCards and setup at IndexPage DISCOVERY-335 --- .../current/intro.mdx | 54 +++++++++++-------- .../current/intro.mdx | 40 +++++++++----- src/shared/ui/nav-card/index.jsx | 10 +++- src/shared/ui/nav-card/styles.module.scss | 37 ++++++++++++- src/shared/ui/nav-card/types.d.ts | 12 +++++ 5 files changed, 114 insertions(+), 39 deletions(-) create mode 100644 src/shared/ui/nav-card/types.d.ts diff --git a/i18n/en/docusaurus-plugin-content-docs/current/intro.mdx b/i18n/en/docusaurus-plugin-content-docs/current/intro.mdx index 65d7a751cf..be955fcbc0 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/intro.mdx +++ b/i18n/en/docusaurus-plugin-content-docs/current/intro.mdx @@ -14,51 +14,63 @@ import NavCard from "@site/src/shared/ui/nav-card/tmpl.mdx" import { RocketOutlined, ThunderboltOutlined, FundViewOutlined } from "@ant-design/icons"; import Link from "@docusaurus/Link"; - + + + +
+ + - - - - - - diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/intro.mdx b/i18n/ru/docusaurus-plugin-content-docs/current/intro.mdx index 1973fd69fc..e599480b4c 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/intro.mdx +++ b/i18n/ru/docusaurus-plugin-content-docs/current/intro.mdx @@ -15,50 +15,62 @@ import { RocketOutlined, ThunderboltOutlined, FundViewOutlined } from "@ant-desi import Link from "@docusaurus/Link"; + + + +
+ + diff --git a/src/shared/ui/nav-card/index.jsx b/src/shared/ui/nav-card/index.jsx index c88bed112b..24543abf75 100644 --- a/src/shared/ui/nav-card/index.jsx +++ b/src/shared/ui/nav-card/index.jsx @@ -8,9 +8,10 @@ import styles from "./styles.module.scss"; /** * NavCard for linking * @see https://docusaurus.io/docs/next/markdown-features/react#importing-markdown + * @param {import('./types').Props} props */ export const NavCard = (props) => { - const { title, description, to, Icon, tags, className, disabled } = props; + const { title, description, to, Icon, tags, className, disabled, theme = "default" } = props; const handleClick = useCallback(() => { ga.sendEvent({ category: ga.CATEGORIES.full, @@ -22,7 +23,12 @@ export const NavCard = (props) => { return ( diff --git a/src/shared/ui/nav-card/styles.module.scss b/src/shared/ui/nav-card/styles.module.scss index 57d7d6cdf5..7f16b3f053 100644 --- a/src/shared/ui/nav-card/styles.module.scss +++ b/src/shared/ui/nav-card/styles.module.scss @@ -46,6 +46,39 @@ margin-bottom: 0; } -html[data-theme="dark"] .root { - background: var(--ifm-color-gray-900); + +// themes +.miniTheme { + padding: 20px 30px; + + + & .title { + font-size: 1rem; + } + + & .details { + filter: grayscale(1); + } + + &:hover .details { + filter: grayscale(0); + } +} + +.primaryTheme { + background-color: var(--ifm-color-primary); + color: #fff; + + &:hover { + color: #fff; + box-shadow: 0 2px 10px 0 var(--ifm-color-primary-neutral); + } } + +// dark-mode +html[data-theme="dark"] .root { + &.defaultTheme, + &.miniTheme { + background: var(--ifm-color-gray-900); + } +} \ No newline at end of file diff --git a/src/shared/ui/nav-card/types.d.ts b/src/shared/ui/nav-card/types.d.ts new file mode 100644 index 0000000000..7f8daf9c40 --- /dev/null +++ b/src/shared/ui/nav-card/types.d.ts @@ -0,0 +1,12 @@ +import type { ReactNode } from "react"; + +export type Props = { + title: ReactNode; + description: ReactNode; + to: string; + Icon: string | any; + tags?: string; + className?: string; + disabled?: boolean; + theme?: "default" | "mini" | "primary"; +}; From a3f66185dac0132cdb669318ab77700025576225 Mon Sep 17 00:00:00 2001 From: Ilya Azin Date: Mon, 19 Sep 2022 11:21:56 +0300 Subject: [PATCH 07/10] fix(index-page): rename QuickStart to Tutorial DISCOVERY-335 --- .../current/get-started/faq.md | 2 +- .../current/get-started/index.mdx | 10 +++++----- .../get-started/{quick-start.md => tutorial.md} | 6 +++--- .../current/get-started/faq.md | 2 +- .../current/get-started/index.mdx | 10 +++++----- .../get-started/{quick-start.md => tutorial.md} | 4 ++-- routes.config.js | 10 +++++----- 7 files changed, 22 insertions(+), 22 deletions(-) rename i18n/en/docusaurus-plugin-content-docs/current/get-started/{quick-start.md => tutorial.md} (99%) rename i18n/ru/docusaurus-plugin-content-docs/current/get-started/{quick-start.md => tutorial.md} (99%) diff --git a/i18n/en/docusaurus-plugin-content-docs/current/get-started/faq.md b/i18n/en/docusaurus-plugin-content-docs/current/get-started/faq.md index 0a952b0454..110ed703d0 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/get-started/faq.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/get-started/faq.md @@ -100,4 +100,4 @@ Otherwise , there is a risk of complicating the project's code base > *"Today, the feature can only be used on one page. Next week - on three. And in a month - it may be removed at all. We cannot predict the future, and we need to refrain from premature optimizations every time"* -*See also the example from [quick-start](/docs/get-started/quick-start#normal-approach)* +*See also the example from [tutorial](/docs/get-started/tutorial#normal-approach)* diff --git a/i18n/en/docusaurus-plugin-content-docs/current/get-started/index.mdx b/i18n/en/docusaurus-plugin-content-docs/current/get-started/index.mdx index 24a8fede49..1eda2983e9 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/get-started/index.mdx +++ b/i18n/en/docusaurus-plugin-content-docs/current/get-started/index.mdx @@ -17,19 +17,19 @@ Welcome! This section helps you to get acquainted with the application of Featur ## Main import NavCard from "@site/src/shared/ui/nav-card/tmpl.mdx" -import { RocketOutlined, BuildOutlined, SettingOutlined } from "@ant-design/icons"; +import { RocketOutlined, BuildOutlined, PlaySquareOutlined } from "@ant-design/icons"; Object.values(tasks)); ```tsx title=pages/tasks-list/index.tsx import { useEffect } from "react"; // If you feel confident with @effector/reflect - can use it -// Within the quick-start non-critical +// Within the tutorial non-critical import { useStore } from "effector"; import { Layout, Row, Col, Typography, Spin, Empty } from "antd"; // ~ "shared/ui/{...}" @@ -638,7 +638,7 @@ export const $tasksFiltered = combine( ```tsx title=features/tasks-filters/ui.tsx // If you feel confident with @effector/reflect, you can immediately use it -// As part of quick-start uncritically +// As part of tutorial uncritically import { useStore } from "effector"; import { Radio } from "antd"; // ~ "shared/ui/radio" diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/get-started/faq.md b/i18n/ru/docusaurus-plugin-content-docs/current/get-started/faq.md index 51dc0af35a..81678728d3 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/get-started/faq.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/get-started/faq.md @@ -100,4 +100,4 @@ pagination_next: guides/index > *"Сегодня фича может использоваться только на одной странице. На следующей неделе - на трех. А через месяц - ее может не быть совсем. Мы не можем предсказывать будущее, и нужно каждый раз воздерживаться от преждевременных оптимизаций"* -*См. также пример из [quick-start](/docs/get-started/quick-start#usual-approach)* +*См. также пример из [tutorial](/docs/get-started/tutorial#usual-approach)* diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/get-started/index.mdx b/i18n/ru/docusaurus-plugin-content-docs/current/get-started/index.mdx index c4dc7f5add..86fce38eec 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/get-started/index.mdx +++ b/i18n/ru/docusaurus-plugin-content-docs/current/get-started/index.mdx @@ -17,19 +17,19 @@ pagination_prev: intro ## Главное {#main} import NavCard from "@site/src/shared/ui/nav-card/tmpl.mdx" -import { RocketOutlined, BuildOutlined, SettingOutlined } from "@ant-design/icons"; +import { RocketOutlined, BuildOutlined, PlaySquareOutlined } from "@ant-design/icons"; Object.values(tasks)); ```tsx title=pages/tasks-list/index.tsx import { useEffect } from "react"; // Если чувствуете себя уверенно с @effector/reflect - можете сразу использовать его -// В рамках quick-start некритично +// В рамках туториала некритично import { useStore } from "effector"; import { Layout, Row, Col, Typography, Spin, Empty } from "antd"; // ~ "shared/ui/{...}" @@ -636,7 +636,7 @@ export const $tasksFiltered = combine( ```tsx title=features/tasks-filters/ui.tsx // Если чувствуете себя уверенно с @effector/reflect - можете сразу использовать его -// В рамках quick-start некритично +// В рамках туториала некритично import { useStore } from "effector"; import { Radio } from "antd"; // ~ "shared/ui/radio" diff --git a/routes.config.js b/routes.config.js index 5e308429e2..c7000dd10a 100644 --- a/routes.config.js +++ b/routes.config.js @@ -8,7 +8,7 @@ const SECTIONS = { fullPath: "/docs/branding", }, MIGRATION: { - shortPath: "//docs/guides/migration", + shortPath: "/docs/guides/migration", fullPath: "/docs/guides/migration/from-legacy", }, }; @@ -23,9 +23,9 @@ const LEGACY_ROUTES = [ details: "Simplified and merged", children: [ { - title: "QuickStart", - from: "/docs/get-started/tutorial/quick-start", - to: "/docs/get-started/quick-start", + title: "Tutorial", + from: "/docs/get-started/quick-start", + to: "/docs/get-started/tutorial", }, { title: "Decompose Cheatsheet", @@ -258,7 +258,7 @@ const _TOTAL_ROUTES = [ "/docs/get-started/overview", "/docs/get-started/cheatsheet", "/docs/get-started/faq", - "/docs/get-started/quick-start", + "/docs/get-started/tutorial", "/docs/guides", "/docs/guides/examples", "/docs/guides/examples/auth", From 76c57f29b8ddfdd962c2bdb809935c08a0d58897 Mon Sep 17 00:00:00 2001 From: Ilya Azin Date: Mon, 19 Sep 2022 11:26:54 +0300 Subject: [PATCH 08/10] fix(index-page): fix broken link DISCOVERY-335 --- .../current/get-started/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/get-started/index.mdx b/i18n/ru/docusaurus-plugin-content-docs/current/get-started/index.mdx index 86fce38eec..17e3fbed26 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/get-started/index.mdx +++ b/i18n/ru/docusaurus-plugin-content-docs/current/get-started/index.mdx @@ -22,7 +22,7 @@ import { RocketOutlined, BuildOutlined, PlaySquareOutlined } from "@ant-design/i Date: Mon, 19 Sep 2022 11:30:53 +0300 Subject: [PATCH 09/10] chore(index-page): lint DISCOVERY-335 --- src/app/index.scss | 4 +++- src/shared/ui/nav-card/styles.module.scss | 12 +++++------- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/src/app/index.scss b/src/app/index.scss index 0de919e28b..33d2cadaba 100644 --- a/src/app/index.scss +++ b/src/app/index.scss @@ -189,6 +189,7 @@ mark { } /* I love adaptive styles... */ + /* FIXME: add unified adaptive breakpoints */ @media (max-width: 1080px) { .navbar__item { @@ -201,9 +202,10 @@ mark { display: block; } } + @media (max-width: 600px) { [role="banner"] { - font-size: 1.0rem; // #nowar + font-size: 1rem; // #nowar } } diff --git a/src/shared/ui/nav-card/styles.module.scss b/src/shared/ui/nav-card/styles.module.scss index 7f16b3f053..4336516e74 100644 --- a/src/shared/ui/nav-card/styles.module.scss +++ b/src/shared/ui/nav-card/styles.module.scss @@ -46,16 +46,14 @@ margin-bottom: 0; } - // themes .miniTheme { padding: 20px 30px; - - + & .title { font-size: 1rem; } - + & .details { filter: grayscale(1); } @@ -66,11 +64,11 @@ } .primaryTheme { + color: #ffffff; background-color: var(--ifm-color-primary); - color: #fff; &:hover { - color: #fff; + color: #ffffff; box-shadow: 0 2px 10px 0 var(--ifm-color-primary-neutral); } } @@ -81,4 +79,4 @@ html[data-theme="dark"] .root { &.miniTheme { background: var(--ifm-color-gray-900); } -} \ No newline at end of file +} From a0858022f5588e54e5ca4e746e19d980b4fe8eff Mon Sep 17 00:00:00 2001 From: Ilya Azin Date: Mon, 19 Sep 2022 11:35:32 +0300 Subject: [PATCH 10/10] fix(index-page): fix typos DISCOVERY-335 --- .../current/get-started/overview.md | 6 ++++-- .../current/get-started/tutorial.md | 2 +- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/get-started/overview.md b/i18n/ru/docusaurus-plugin-content-docs/current/get-started/overview.md index cb601f8bbd..53642dcc1c 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/get-started/overview.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/get-started/overview.md @@ -2,7 +2,7 @@ sidebar_position: 1 --- -# Основы {#basics} +# Обзор ## Подходит ли это мне? {#is-it-right-for-me} @@ -19,7 +19,7 @@ FSD подходит для проектов и команд любого раз ## Основы {#basics} -Проект на FSD состоит из слоев (layers), каждый слой состоит из слайсов (slices) и каждый слайс состоит из слайсов (segments). +Проект на FSD состоит из слоев (layers), каждый слой состоит из слайсов (slices) и каждый слайс состоит из сегментов (segments). ![themed--scheme](/img/visual_schema.jpg) @@ -98,3 +98,5 @@ FSD подходит для проектов и команд любого раз [refs-examples]: /examples [refs-migration]: /docs/guides/migration [refs-splitting]: /docs/concepts/app-splitting +[refs-wiki-cohesion]: https://ru.wikipedia.org/wiki/%D0%A1%D0%B2%D1%8F%D0%B7%D0%BD%D0%BE%D1%81%D1%82%D1%8C_(%D0%BF%D1%80%D0%BE%D0%B3%D1%80%D0%B0%D0%BC%D0%BC%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5) +[refs-wiki-coupling]: https://ru.wikipedia.org/wiki/%D0%97%D0%B0%D1%86%D0%B5%D0%BF%D0%BB%D0%B5%D0%BD%D0%B8%D0%B5_(%D0%BF%D1%80%D0%BE%D0%B3%D1%80%D0%B0%D0%BC%D0%BC%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5) \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/get-started/tutorial.md b/i18n/ru/docusaurus-plugin-content-docs/current/get-started/tutorial.md index bcced853ba..0c59ec7b2c 100644 --- a/i18n/ru/docusaurus-plugin-content-docs/current/get-started/tutorial.md +++ b/i18n/ru/docusaurus-plugin-content-docs/current/get-started/tutorial.md @@ -2,7 +2,7 @@ sidebar_position: 2 --- -# Быстрый старт +# Туториал Рассмотрим применение **Feature-Sliced Design** на примере TodoApp