diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml index 306799a4..61855c30 100644 --- a/.github/workflows/check.yml +++ b/.github/workflows/check.yml @@ -39,35 +39,76 @@ jobs: - name: Lint run: pnpm lint - test: - runs-on: ubuntu-latest - - steps: - - name: Checkout Code - uses: actions/checkout@v6 - - - name: Set up Node.js and pnpm using mise - uses: jdx/mise-action@v3 - - - name: Get pnpm store directory - id: pnpm-cache - shell: bash - run: | - echo "STORE_PATH=$(pnpm store path)" >> $GITHUB_OUTPUT - - - name: Setup pnpm cache - uses: actions/cache@v4 - with: - path: ${{ steps.pnpm-cache.outputs.STORE_PATH }} - key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }} - restore-keys: | - ${{ runner.os }}-pnpm-store- - - - name: Install dependencies - run: pnpm install --frozen-lockfile - - - name: Test - run: pnpm test + test: + runs-on: ubuntu-latest + + steps: + - name: Checkout Code + uses: actions/checkout@v6 + + - name: Set up Node.js and pnpm using mise + uses: jdx/mise-action@v3 + + - name: Get pnpm store directory + id: pnpm-cache + shell: bash + run: | + echo "STORE_PATH=$(pnpm store path)" >> $GITHUB_OUTPUT + + - name: Setup pnpm cache + uses: actions/cache@v4 + with: + path: ${{ steps.pnpm-cache.outputs.STORE_PATH }} + key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }} + restore-keys: | + ${{ runner.os }}-pnpm-store- + + - name: Install dependencies + run: pnpm install --frozen-lockfile + + - name: Test + run: pnpm test + + e2e: + runs-on: ubuntu-latest + + steps: + - name: Checkout Code + uses: actions/checkout@v6 + + - name: Set up Node.js and pnpm using mise + uses: jdx/mise-action@v3 + + - name: Get pnpm store directory + id: pnpm-cache + shell: bash + run: | + echo "STORE_PATH=$(pnpm store path)" >> $GITHUB_OUTPUT + + - name: Setup pnpm cache + uses: actions/cache@v4 + with: + path: ${{ steps.pnpm-cache.outputs.STORE_PATH }} + key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }} + restore-keys: | + ${{ runner.os }}-pnpm-store- + + - name: Install dependencies + run: pnpm install --frozen-lockfile + + - name: Install Playwright Browsers + run: pnpm --filter @nipsys/lsd-docs exec playwright install --with-deps chromium + + - name: Run E2E tests + run: pnpm docs:test:e2e + + - name: Upload test results + if: always() + uses: actions/upload-artifact@v4 + with: + name: playwright-report + path: packages/lsd-docs/playwright-report/ + build: runs-on: ubuntu-latest diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 93b0c8c0..63b6d061 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -70,4 +70,4 @@ jobs: - name: Publish to npm run: | pnpm config set registry 'https://registry.npmjs.org' - pnpm --filter @nipsys/shadcn-lsd publish --provenance --access public --no-git-checks + pnpm --filter @nipsys/lsd publish --provenance --access public --no-git-checks diff --git a/.gitignore b/.gitignore index cbda8e7a..5a458041 100644 --- a/.gitignore +++ b/.gitignore @@ -47,6 +47,7 @@ coverage *.pem ai_docs .kilocode +.kilo *.tgz plans @@ -59,4 +60,6 @@ plans # typescript *.tsbuildinfo -docs/dev \ No newline at end of file +/docs +playwright-report +test-results \ No newline at end of file diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..1a546e5b --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,92 @@ + +# Contributor Covenant 3.0 Code of Conduct + +## Our Pledge + +We pledge to make our community welcoming, safe, and equitable for all. + +We are committed to fostering an environment that respects and promotes the dignity, rights, and contributions of all individuals, regardless of characteristics including race, ethnicity, caste, color, age, physical characteristics, neurodiversity, disability, sex or gender, gender identity or expression, sexual orientation, language, philosophy or religion, national or social origin, socio-economic position, level of education, or other status. The same privileges of participation are extended to everyone who participates in good faith and in accordance with this Covenant. + +## Encouraged Behaviors + +While acknowledging differences in social norms, we all strive to meet our community's expectations for positive behavior. We also understand that our words and actions may be interpreted differently than we intend based on culture, background, or native language. + +With these considerations in mind, we agree to behave mindfully toward each other and act in ways that center our shared values, including: + +1. Respecting the **purpose of our community**, our activities, and our ways of gathering. +2. Engaging **kindly and honestly** with others. +3. Respecting **different viewpoints** and experiences. +4. **Taking responsibility** for our actions and contributions. +5. Gracefully giving and accepting **constructive feedback**. +6. Committing to **repairing harm** when it occurs. +7. Behaving in other ways that promote and sustain the **well-being of our community**. + + +## Restricted Behaviors + +We agree to restrict the following behaviors in our community. Instances, threats, and promotion of these behaviors are violations of this Code of Conduct. + +1. **Harassment.** Violating explicitly expressed boundaries or engaging in unnecessary personal attention after any clear request to stop. +2. **Character attacks.** Making insulting, demeaning, or pejorative comments directed at a community member or group of people. +3. **Stereotyping or discrimination.** Characterizing anyone’s personality or behavior on the basis of immutable identities or traits. +4. **Sexualization.** Behaving in a way that would generally be considered inappropriately intimate in the context or purpose of the community. +5. **Violating confidentiality**. Sharing or acting on someone's personal or private information without their permission. +6. **Endangerment.** Causing, encouraging, or threatening violence or other harm toward any person or group. +7. Behaving in other ways that **threaten the well-being** of our community. + +### Other Restrictions + +1. **Misleading identity.** Impersonating someone else for any reason, or pretending to be someone else to evade enforcement actions. +2. **Failing to credit sources.** Not properly crediting the sources of content you contribute. +3. **Promotional materials**. Sharing marketing or other commercial content in a way that is outside the norms of the community. +4. **Irresponsible communication.** Failing to responsibly present content which includes, links or describes any other restricted behaviors. + + +## Reporting an Issue + +Tensions can occur between community members even when they are trying their best to collaborate. Not every conflict represents a code of conduct violation, and this Code of Conduct reinforces encouraged behaviors and norms that can help avoid conflicts and minimize harm. + +When an incident does occur, it is important to report it promptly. To report a possible violation, **reach out to Xav, the owner of this repository. See https://nipsys.eth.limo/en/contact/ for different ways of reaching out.** + +Community Moderators take reports of violations seriously and will make every effort to respond in a timely manner. They will investigate all reports of code of conduct violations, reviewing messages, logs, and recordings, or interviewing witnesses and other participants. Community Moderators will keep investigation and enforcement actions as transparent as possible while prioritizing safety and confidentiality. In order to honor these values, enforcement actions are carried out in private with the involved parties, but communicating to the whole community may be part of a mutually agreed upon resolution. + + +## Addressing and Repairing Harm + +**** + +If an investigation by the Community Moderators finds that this Code of Conduct has been violated, the following enforcement ladder may be used to determine how best to repair harm, based on the incident's impact on the individuals involved and the community as a whole. Depending on the severity of a violation, lower rungs on the ladder may be skipped. + +1) Warning + 1) Event: A violation involving a single incident or series of incidents. + 2) Consequence: A private, written warning from the Community Moderators. + 3) Repair: Examples of repair include a private written apology, acknowledgement of responsibility, and seeking clarification on expectations. +2) Temporarily Limited Activities + 1) Event: A repeated incidence of a violation that previously resulted in a warning, or the first incidence of a more serious violation. + 2) Consequence: A private, written warning with a time-limited cooldown period designed to underscore the seriousness of the situation and give the community members involved time to process the incident. The cooldown period may be limited to particular communication channels or interactions with particular community members. + 3) Repair: Examples of repair may include making an apology, using the cooldown period to reflect on actions and impact, and being thoughtful about re-entering community spaces after the period is over. +3) Temporary Suspension + 1) Event: A pattern of repeated violation which the Community Moderators have tried to address with warnings, or a single serious violation. + 2) Consequence: A private written warning with conditions for return from suspension. In general, temporary suspensions give the person being suspended time to reflect upon their behavior and possible corrective actions. + 3) Repair: Examples of repair include respecting the spirit of the suspension, meeting the specified conditions for return, and being thoughtful about how to reintegrate with the community when the suspension is lifted. +4) Permanent Ban + 1) Event: A pattern of repeated code of conduct violations that other steps on the ladder have failed to resolve, or a violation so serious that the Community Moderators determine there is no way to keep the community safe with this person as a member. + 2) Consequence: Access to all community spaces, tools, and communication channels is removed. In general, permanent bans should be rarely used, should have strong reasoning behind them, and should only be resorted to if working through other remedies has failed to change the behavior. + 3) Repair: There is no possible repair in cases of this severity. + +This enforcement ladder is intended as a guideline. It does not limit the ability of Community Managers to use their discretion and judgment, in keeping with the best interests of our community. + + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public or other spaces. Examples of representing our community include using an official email address, posting via an official social media account, or acting as an appointed representative at an online or offline event. + + +## Attribution + +This Code of Conduct is adapted from the Contributor Covenant, version 3.0, permanently available at [https://www.contributor-covenant.org/version/3/0/](https://www.contributor-covenant.org/version/3/0/). + +Contributor Covenant is stewarded by the Organization for Ethical Source and licensed under CC BY-SA 4.0. To view a copy of this license, visit [https://creativecommons.org/licenses/by-sa/4.0/](https://creativecommons.org/licenses/by-sa/4.0/) + +For answers to common questions about Contributor Covenant, see the FAQ at [https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq). Translations are provided at [https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations). Additional enforcement and community guideline resources can be found at [https://www.contributor-covenant.org/resources](https://www.contributor-covenant.org/resources). The enforcement ladder was inspired by the work of [Mozilla’s code of conduct team](https://github.com/mozilla/inclusion). + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..7fbc81f2 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,70 @@ +# Contributing to shadcn-lsd + +Welcome to the shadcn-lsd component library! We're excited to have you as a contributor. Before you get started, please read the following guidelines to ensure your contributions align with our project goals. + +## Code of Conduct + +We expect all contributors to adhere to our [Code of Conduct](./CODE_OF_CONDUCT.md). We are committed to creating a welcoming and inclusive environment for everyone and will not tolerate any form of harassment or discrimination. + +## Getting Started + +To contribute to shadcn-lsd: + +1. Fork the repository to your own GitHub account +2. Clone your fork locally +3. Create a new branch for your changes +4. Make your changes +5. Push your changes to your fork +6. Create a pull request to merge into the main repository + +## Types of Contributions + +### Issues and Feature Requests + +If you discover a bug or have an idea for a new feature, please submit an issue in our [GitHub issue tracker](https://github.com/nipsysdev/lsd/issues). Include: +- A clear and descriptive title +- Detailed description of the problem or feature request +- Steps to reproduce (for bugs) +- Expected behavior vs actual behavior (for bugs) + +If there's already an open issue for something you'd like to work on, please check in the comments or open a discussion before you start—someone else might already be working on it. + +### Pull Requests + +When submitting a pull request, please follow these guidelines: + +- **Clear description:** Explain the changes you've made and why they're necessary +- **Test coverage:** Include tests that demonstrate your changes +- **Code quality:** Follow existing coding standards and patterns +- **Focused changes:** Keep your PR focused on a single issue or feature +- **Documentation:** Update relevant documentation if needed +- **Responsive:** Be open to feedback and address review comments + +### Review Process + +All pull requests are reviewed by maintainers. We aim to review and respond within a reasonable timeframe. If your PR requires changes, you'll receive clear feedback on what needs addressing. + +## Contribution Areas + +We welcome contributions in several areas: + +- **New components:** Add UI components to the lsd package using shadcn/ui +- **Component improvements:** Enhance existing components with new features or better accessibility +- **Documentation:** Improve documentation clarity, add examples, or fix inaccuracies +- **Bug fixes:** Resolve issues reported in the tracker +- **Tests:** Improve test coverage or add e2e tests for examples + +## Commit Messages + +We use [Conventional Commits](https://www.conventionalcommits.org/) for commit messages. This helps with automated changelog generation and version management. Examples: + +- `feat: add border-radius variant to button component` +- `fix: resolve dialog focus trap issue` +- `docs: improve autocomplete installation instructions` +- `test: add e2e tests for select component` + +## License + +By contributing to shadcn-lsd, you agree that your contributions will be licensed under the same [MIT License](./LICENSE.md) as the project. + +Thank you for helping improve shadcn-lsd! diff --git a/LICENSE b/LICENSE index 4838f22c..9bcf419f 100644 --- a/LICENSE +++ b/LICENSE @@ -1,674 +1,21 @@ - GNU GENERAL PUBLIC LICENSE - Version 3, 29 June 2007 - - Copyright (C) 2007 Free Software Foundation, Inc. - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - Preamble - - The GNU General Public License is a free, copyleft license for -software and other kinds of works. - - The licenses for most software and other practical works are designed -to take away your freedom to share and change the works. By contrast, -the GNU General Public License is intended to guarantee your freedom to -share and change all versions of a program--to make sure it remains free -software for all its users. We, the Free Software Foundation, use the -GNU General Public License for most of our software; it applies also to -any other work released this way by its authors. You can apply it to -your programs, too. - - When we speak of free software, we are referring to freedom, not -price. Our General Public Licenses are designed to make sure that you -have the freedom to distribute copies of free software (and charge for -them if you wish), that you receive source code or can get it if you -want it, that you can change the software or use pieces of it in new -free programs, and that you know you can do these things. - - To protect your rights, we need to prevent others from denying you -these rights or asking you to surrender the rights. Therefore, you have -certain responsibilities if you distribute copies of the software, or if -you modify it: responsibilities to respect the freedom of others. - - For example, if you distribute copies of such a program, whether -gratis or for a fee, you must pass on to the recipients the same -freedoms that you received. You must make sure that they, too, receive -or can get the source code. And you must show them these terms so they -know their rights. - - Developers that use the GNU GPL protect your rights with two steps: -(1) assert copyright on the software, and (2) offer you this License -giving you legal permission to copy, distribute and/or modify it. - - For the developers' and authors' protection, the GPL clearly explains -that there is no warranty for this free software. For both users' and -authors' sake, the GPL requires that modified versions be marked as -changed, so that their problems will not be attributed erroneously to -authors of previous versions. - - Some devices are designed to deny users access to install or run -modified versions of the software inside them, although the manufacturer -can do so. This is fundamentally incompatible with the aim of -protecting users' freedom to change the software. The systematic -pattern of such abuse occurs in the area of products for individuals to -use, which is precisely where it is most unacceptable. Therefore, we -have designed this version of the GPL to prohibit the practice for those -products. If such problems arise substantially in other domains, we -stand ready to extend this provision to those domains in future versions -of the GPL, as needed to protect the freedom of users. - - Finally, every program is threatened constantly by software patents. -States should not allow patents to restrict development and use of -software on general-purpose computers, but in those that do, we wish to -avoid the special danger that patents applied to a free program could -make it effectively proprietary. To prevent this, the GPL assures that -patents cannot be used to render the program non-free. - - The precise terms and conditions for copying, distribution and -modification follow. - - TERMS AND CONDITIONS - - 0. Definitions. - - "This License" refers to version 3 of the GNU General Public License. - - "Copyright" also means copyright-like laws that apply to other kinds of -works, such as semiconductor masks. - - "The Program" refers to any copyrightable work licensed under this -License. Each licensee is addressed as "you". "Licensees" and -"recipients" may be individuals or organizations. - - To "modify" a work means to copy from or adapt all or part of the work -in a fashion requiring copyright permission, other than the making of an -exact copy. The resulting work is called a "modified version" of the -earlier work or a work "based on" the earlier work. - - A "covered work" means either the unmodified Program or a work based -on the Program. - - To "propagate" a work means to do anything with it that, without -permission, would make you directly or secondarily liable for -infringement under applicable copyright law, except executing it on a -computer or modifying a private copy. Propagation includes copying, -distribution (with or without modification), making available to the -public, and in some countries other activities as well. - - To "convey" a work means any kind of propagation that enables other -parties to make or receive copies. Mere interaction with a user through -a computer network, with no transfer of a copy, is not conveying. - - An interactive user interface displays "Appropriate Legal Notices" -to the extent that it includes a convenient and prominently visible -feature that (1) displays an appropriate copyright notice, and (2) -tells the user that there is no warranty for the work (except to the -extent that warranties are provided), that licensees may convey the -work under this License, and how to view a copy of this License. If -the interface presents a list of user commands or options, such as a -menu, a prominent item in the list meets this criterion. - - 1. Source Code. - - The "source code" for a work means the preferred form of the work -for making modifications to it. "Object code" means any non-source -form of a work. - - A "Standard Interface" means an interface that either is an official -standard defined by a recognized standards body, or, in the case of -interfaces specified for a particular programming language, one that -is widely used among developers working in that language. - - The "System Libraries" of an executable work include anything, other -than the work as a whole, that (a) is included in the normal form of -packaging a Major Component, but which is not part of that Major -Component, and (b) serves only to enable use of the work with that -Major Component, or to implement a Standard Interface for which an -implementation is available to the public in source code form. A -"Major Component", in this context, means a major essential component -(kernel, window system, and so on) of the specific operating system -(if any) on which the executable work runs, or a compiler used to -produce the work, or an object code interpreter used to run it. - - The "Corresponding Source" for a work in object code form means all -the source code needed to generate, install, and (for an executable -work) run the object code and to modify the work, including scripts to -control those activities. However, it does not include the work's -System Libraries, or general-purpose tools or generally available free -programs which are used unmodified in performing those activities but -which are not part of the work. For example, Corresponding Source -includes interface definition files associated with source files for -the work, and the source code for shared libraries and dynamically -linked subprograms that the work is specifically designed to require, -such as by intimate data communication or control flow between those -subprograms and other parts of the work. - - The Corresponding Source need not include anything that users -can regenerate automatically from other parts of the Corresponding -Source. - - The Corresponding Source for a work in source code form is that -same work. - - 2. Basic Permissions. - - All rights granted under this License are granted for the term of -copyright on the Program, and are irrevocable provided the stated -conditions are met. This License explicitly affirms your unlimited -permission to run the unmodified Program. The output from running a -covered work is covered by this License only if the output, given its -content, constitutes a covered work. This License acknowledges your -rights of fair use or other equivalent, as provided by copyright law. - - You may make, run and propagate covered works that you do not -convey, without conditions so long as your license otherwise remains -in force. You may convey covered works to others for the sole purpose -of having them make modifications exclusively for you, or provide you -with facilities for running those works, provided that you comply with -the terms of this License in conveying all material for which you do -not control copyright. Those thus making or running the covered works -for you must do so exclusively on your behalf, under your direction -and control, on terms that prohibit them from making any copies of -your copyrighted material outside their relationship with you. - - Conveying under any other circumstances is permitted solely under -the conditions stated below. Sublicensing is not allowed; section 10 -makes it unnecessary. - - 3. Protecting Users' Legal Rights From Anti-Circumvention Law. - - No covered work shall be deemed part of an effective technological -measure under any applicable law fulfilling obligations under article -11 of the WIPO copyright treaty adopted on 20 December 1996, or -similar laws prohibiting or restricting circumvention of such -measures. - - When you convey a covered work, you waive any legal power to forbid -circumvention of technological measures to the extent such circumvention -is effected by exercising rights under this License with respect to -the covered work, and you disclaim any intention to limit operation or -modification of the work as a means of enforcing, against the work's -users, your or third parties' legal rights to forbid circumvention of -technological measures. - - 4. Conveying Verbatim Copies. - - You may convey verbatim copies of the Program's source code as you -receive it, in any medium, provided that you conspicuously and -appropriately publish on each copy an appropriate copyright notice; -keep intact all notices stating that this License and any -non-permissive terms added in accord with section 7 apply to the code; -keep intact all notices of the absence of any warranty; and give all -recipients a copy of this License along with the Program. - - You may charge any price or no price for each copy that you convey, -and you may offer support or warranty protection for a fee. - - 5. Conveying Modified Source Versions. - - You may convey a work based on the Program, or the modifications to -produce it from the Program, in the form of source code under the -terms of section 4, provided that you also meet all of these conditions: - - a) The work must carry prominent notices stating that you modified - it, and giving a relevant date. - - b) The work must carry prominent notices stating that it is - released under this License and any conditions added under section - 7. This requirement modifies the requirement in section 4 to - "keep intact all notices". - - c) You must license the entire work, as a whole, under this - License to anyone who comes into possession of a copy. This - License will therefore apply, along with any applicable section 7 - additional terms, to the whole of the work, and all its parts, - regardless of how they are packaged. This License gives no - permission to license the work in any other way, but it does not - invalidate such permission if you have separately received it. - - d) If the work has interactive user interfaces, each must display - Appropriate Legal Notices; however, if the Program has interactive - interfaces that do not display Appropriate Legal Notices, your - work need not make them do so. - - A compilation of a covered work with other separate and independent -works, which are not by their nature extensions of the covered work, -and which are not combined with it such as to form a larger program, -in or on a volume of a storage or distribution medium, is called an -"aggregate" if the compilation and its resulting copyright are not -used to limit the access or legal rights of the compilation's users -beyond what the individual works permit. Inclusion of a covered work -in an aggregate does not cause this License to apply to the other -parts of the aggregate. - - 6. Conveying Non-Source Forms. - - You may convey a covered work in object code form under the terms -of sections 4 and 5, provided that you also convey the -machine-readable Corresponding Source under the terms of this License, -in one of these ways: - - a) Convey the object code in, or embodied in, a physical product - (including a physical distribution medium), accompanied by the - Corresponding Source fixed on a durable physical medium - customarily used for software interchange. - - b) Convey the object code in, or embodied in, a physical product - (including a physical distribution medium), accompanied by a - written offer, valid for at least three years and valid for as - long as you offer spare parts or customer support for that product - model, to give anyone who possesses the object code either (1) a - copy of the Corresponding Source for all the software in the - product that is covered by this License, on a durable physical - medium customarily used for software interchange, for a price no - more than your reasonable cost of physically performing this - conveying of source, or (2) access to copy the - Corresponding Source from a network server at no charge. - - c) Convey individual copies of the object code with a copy of the - written offer to provide the Corresponding Source. This - alternative is allowed only occasionally and noncommercially, and - only if you received the object code with such an offer, in accord - with subsection 6b. - - d) Convey the object code by offering access from a designated - place (gratis or for a charge), and offer equivalent access to the - Corresponding Source in the same way through the same place at no - further charge. You need not require recipients to copy the - Corresponding Source along with the object code. If the place to - copy the object code is a network server, the Corresponding Source - may be on a different server (operated by you or a third party) - that supports equivalent copying facilities, provided you maintain - clear directions next to the object code saying where to find the - Corresponding Source. Regardless of what server hosts the - Corresponding Source, you remain obligated to ensure that it is - available for as long as needed to satisfy these requirements. - - e) Convey the object code using peer-to-peer transmission, provided - you inform other peers where the object code and Corresponding - Source of the work are being offered to the general public at no - charge under subsection 6d. - - A separable portion of the object code, whose source code is excluded -from the Corresponding Source as a System Library, need not be -included in conveying the object code work. - - A "User Product" is either (1) a "consumer product", which means any -tangible personal property which is normally used for personal, family, -or household purposes, or (2) anything designed or sold for incorporation -into a dwelling. In determining whether a product is a consumer product, -doubtful cases shall be resolved in favor of coverage. For a particular -product received by a particular user, "normally used" refers to a -typical or common use of that class of product, regardless of the status -of the particular user or of the way in which the particular user -actually uses, or expects or is expected to use, the product. A product -is a consumer product regardless of whether the product has substantial -commercial, industrial or non-consumer uses, unless such uses represent -the only significant mode of use of the product. - - "Installation Information" for a User Product means any methods, -procedures, authorization keys, or other information required to install -and execute modified versions of a covered work in that User Product from -a modified version of its Corresponding Source. The information must -suffice to ensure that the continued functioning of the modified object -code is in no case prevented or interfered with solely because -modification has been made. - - If you convey an object code work under this section in, or with, or -specifically for use in, a User Product, and the conveying occurs as -part of a transaction in which the right of possession and use of the -User Product is transferred to the recipient in perpetuity or for a -fixed term (regardless of how the transaction is characterized), the -Corresponding Source conveyed under this section must be accompanied -by the Installation Information. But this requirement does not apply -if neither you nor any third party retains the ability to install -modified object code on the User Product (for example, the work has -been installed in ROM). - - The requirement to provide Installation Information does not include a -requirement to continue to provide support service, warranty, or updates -for a work that has been modified or installed by the recipient, or for -the User Product in which it has been modified or installed. Access to a -network may be denied when the modification itself materially and -adversely affects the operation of the network or violates the rules and -protocols for communication across the network. - - Corresponding Source conveyed, and Installation Information provided, -in accord with this section must be in a format that is publicly -documented (and with an implementation available to the public in -source code form), and must require no special password or key for -unpacking, reading or copying. - - 7. Additional Terms. - - "Additional permissions" are terms that supplement the terms of this -License by making exceptions from one or more of its conditions. -Additional permissions that are applicable to the entire Program shall -be treated as though they were included in this License, to the extent -that they are valid under applicable law. If additional permissions -apply only to part of the Program, that part may be used separately -under those permissions, but the entire Program remains governed by -this License without regard to the additional permissions. - - When you convey a copy of a covered work, you may at your option -remove any additional permissions from that copy, or from any part of -it. (Additional permissions may be written to require their own -removal in certain cases when you modify the work.) You may place -additional permissions on material, added by you to a covered work, -for which you have or can give appropriate copyright permission. - - Notwithstanding any other provision of this License, for material you -add to a covered work, you may (if authorized by the copyright holders of -that material) supplement the terms of this License with terms: - - a) Disclaiming warranty or limiting liability differently from the - terms of sections 15 and 16 of this License; or - - b) Requiring preservation of specified reasonable legal notices or - author attributions in that material or in the Appropriate Legal - Notices displayed by works containing it; or - - c) Prohibiting misrepresentation of the origin of that material, or - requiring that modified versions of such material be marked in - reasonable ways as different from the original version; or - - d) Limiting the use for publicity purposes of names of licensors or - authors of the material; or - - e) Declining to grant rights under trademark law for use of some - trade names, trademarks, or service marks; or - - f) Requiring indemnification of licensors and authors of that - material by anyone who conveys the material (or modified versions of - it) with contractual assumptions of liability to the recipient, for - any liability that these contractual assumptions directly impose on - those licensors and authors. - - All other non-permissive additional terms are considered "further -restrictions" within the meaning of section 10. If the Program as you -received it, or any part of it, contains a notice stating that it is -governed by this License along with a term that is a further -restriction, you may remove that term. If a license document contains -a further restriction but permits relicensing or conveying under this -License, you may add to a covered work material governed by the terms -of that license document, provided that the further restriction does -not survive such relicensing or conveying. - - If you add terms to a covered work in accord with this section, you -must place, in the relevant source files, a statement of the -additional terms that apply to those files, or a notice indicating -where to find the applicable terms. - - Additional terms, permissive or non-permissive, may be stated in the -form of a separately written license, or stated as exceptions; -the above requirements apply either way. - - 8. Termination. - - You may not propagate or modify a covered work except as expressly -provided under this License. Any attempt otherwise to propagate or -modify it is void, and will automatically terminate your rights under -this License (including any patent licenses granted under the third -paragraph of section 11). - - However, if you cease all violation of this License, then your -license from a particular copyright holder is reinstated (a) -provisionally, unless and until the copyright holder explicitly and -finally terminates your license, and (b) permanently, if the copyright -holder fails to notify you of the violation by some reasonable means -prior to 60 days after the cessation. - - Moreover, your license from a particular copyright holder is -reinstated permanently if the copyright holder notifies you of the -violation by some reasonable means, this is the first time you have -received notice of violation of this License (for any work) from that -copyright holder, and you cure the violation prior to 30 days after -your receipt of the notice. - - Termination of your rights under this section does not terminate the -licenses of parties who have received copies or rights from you under -this License. If your rights have been terminated and not permanently -reinstated, you do not qualify to receive new licenses for the same -material under section 10. - - 9. Acceptance Not Required for Having Copies. - - You are not required to accept this License in order to receive or -run a copy of the Program. Ancillary propagation of a covered work -occurring solely as a consequence of using peer-to-peer transmission -to receive a copy likewise does not require acceptance. However, -nothing other than this License grants you permission to propagate or -modify any covered work. These actions infringe copyright if you do -not accept this License. Therefore, by modifying or propagating a -covered work, you indicate your acceptance of this License to do so. - - 10. Automatic Licensing of Downstream Recipients. - - Each time you convey a covered work, the recipient automatically -receives a license from the original licensors, to run, modify and -propagate that work, subject to this License. You are not responsible -for enforcing compliance by third parties with this License. - - An "entity transaction" is a transaction transferring control of an -organization, or substantially all assets of one, or subdividing an -organization, or merging organizations. If propagation of a covered -work results from an entity transaction, each party to that -transaction who receives a copy of the work also receives whatever -licenses to the work the party's predecessor in interest had or could -give under the previous paragraph, plus a right to possession of the -Corresponding Source of the work from the predecessor in interest, if -the predecessor has it or can get it with reasonable efforts. - - You may not impose any further restrictions on the exercise of the -rights granted or affirmed under this License. For example, you may -not impose a license fee, royalty, or other charge for exercise of -rights granted under this License, and you may not initiate litigation -(including a cross-claim or counterclaim in a lawsuit) alleging that -any patent claim is infringed by making, using, selling, offering for -sale, or importing the Program or any portion of it. - - 11. Patents. - - A "contributor" is a copyright holder who authorizes use under this -License of the Program or a work on which the Program is based. The -work thus licensed is called the contributor's "contributor version". - - A contributor's "essential patent claims" are all patent claims -owned or controlled by the contributor, whether already acquired or -hereafter acquired, that would be infringed by some manner, permitted -by this License, of making, using, or selling its contributor version, -but do not include claims that would be infringed only as a -consequence of further modification of the contributor version. For -purposes of this definition, "control" includes the right to grant -patent sublicenses in a manner consistent with the requirements of -this License. - - Each contributor grants you a non-exclusive, worldwide, royalty-free -patent license under the contributor's essential patent claims, to -make, use, sell, offer for sale, import and otherwise run, modify and -propagate the contents of its contributor version. - - In the following three paragraphs, a "patent license" is any express -agreement or commitment, however denominated, not to enforce a patent -(such as an express permission to practice a patent or covenant not to -sue for patent infringement). To "grant" such a patent license to a -party means to make such an agreement or commitment not to enforce a -patent against the party. - - If you convey a covered work, knowingly relying on a patent license, -and the Corresponding Source of the work is not available for anyone -to copy, free of charge and under the terms of this License, through a -publicly available network server or other readily accessible means, -then you must either (1) cause the Corresponding Source to be so -available, or (2) arrange to deprive yourself of the benefit of the -patent license for this particular work, or (3) arrange, in a manner -consistent with the requirements of this License, to extend the patent -license to downstream recipients. "Knowingly relying" means you have -actual knowledge that, but for the patent license, your conveying the -covered work in a country, or your recipient's use of the covered work -in a country, would infringe one or more identifiable patents in that -country that you have reason to believe are valid. - - If, pursuant to or in connection with a single transaction or -arrangement, you convey, or propagate by procuring conveyance of, a -covered work, and grant a patent license to some of the parties -receiving the covered work authorizing them to use, propagate, modify -or convey a specific copy of the covered work, then the patent license -you grant is automatically extended to all recipients of the covered -work and works based on it. - - A patent license is "discriminatory" if it does not include within -the scope of its coverage, prohibits the exercise of, or is -conditioned on the non-exercise of one or more of the rights that are -specifically granted under this License. You may not convey a covered -work if you are a party to an arrangement with a third party that is -in the business of distributing software, under which you make payment -to the third party based on the extent of your activity of conveying -the work, and under which the third party grants, to any of the -parties who would receive the covered work from you, a discriminatory -patent license (a) in connection with copies of the covered work -conveyed by you (or copies made from those copies), or (b) primarily -for and in connection with specific products or compilations that -contain the covered work, unless you entered into that arrangement, -or that patent license was granted, prior to 28 March 2007. - - Nothing in this License shall be construed as excluding or limiting -any implied license or other defenses to infringement that may -otherwise be available to you under applicable patent law. - - 12. No Surrender of Others' Freedom. - - If conditions are imposed on you (whether by court order, agreement or -otherwise) that contradict the conditions of this License, they do not -excuse you from the conditions of this License. If you cannot convey a -covered work so as to satisfy simultaneously your obligations under this -License and any other pertinent obligations, then as a consequence you may -not convey it at all. For example, if you agree to terms that obligate you -to collect a royalty for further conveying from those to whom you convey -the Program, the only way you could satisfy both those terms and this -License would be to refrain entirely from conveying the Program. - - 13. Use with the GNU Affero General Public License. - - Notwithstanding any other provision of this License, you have -permission to link or combine any covered work with a work licensed -under version 3 of the GNU Affero General Public License into a single -combined work, and to convey the resulting work. The terms of this -License will continue to apply to the part which is the covered work, -but the special requirements of the GNU Affero General Public License, -section 13, concerning interaction through a network will apply to the -combination as such. - - 14. Revised Versions of this License. - - The Free Software Foundation may publish revised and/or new versions of -the GNU General Public License from time to time. Such new versions will -be similar in spirit to the present version, but may differ in detail to -address new problems or concerns. - - Each version is given a distinguishing version number. If the -Program specifies that a certain numbered version of the GNU General -Public License "or any later version" applies to it, you have the -option of following the terms and conditions either of that numbered -version or of any later version published by the Free Software -Foundation. If the Program does not specify a version number of the -GNU General Public License, you may choose any version ever published -by the Free Software Foundation. - - If the Program specifies that a proxy can decide which future -versions of the GNU General Public License can be used, that proxy's -public statement of acceptance of a version permanently authorizes you -to choose that version for the Program. - - Later license versions may give you additional or different -permissions. However, no additional obligations are imposed on any -author or copyright holder as a result of your choosing to follow a -later version. - - 15. Disclaimer of Warranty. - - THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY -APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT -HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY -OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, -THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR -PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM -IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF -ALL NECESSARY SERVICING, REPAIR OR CORRECTION. - - 16. Limitation of Liability. - - IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING -WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS -THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY -GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE -USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF -DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD -PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), -EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF -SUCH DAMAGES. - - 17. Interpretation of Sections 15 and 16. - - If the disclaimer of warranty and limitation of liability provided -above cannot be given local legal effect according to their terms, -reviewing courts shall apply local law that most closely approximates -an absolute waiver of all civil liability in connection with the -Program, unless a warranty or assumption of liability accompanies a -copy of the Program in return for a fee. - - END OF TERMS AND CONDITIONS - - How to Apply These Terms to Your New Programs - - If you develop a new program, and you want it to be of the greatest -possible use to the public, the best way to achieve this is to make it -free software which everyone can redistribute and change under these terms. - - To do so, attach the following notices to the program. It is safest -to attach them to the start of each source file to most effectively -state the exclusion of warranty; and each file should have at least -the "copyright" line and a pointer to where the full notice is found. - - @nipsys/shadcn-lsd is a UI component library based on the Logos Design System - Copyright (C) 2025 Xavier Saliniere - - This program is free software: you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation, either version 3 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see . - -Also add information on how to contact you by electronic and paper mail. - - If the program does terminal interaction, make it output a short -notice like this when it starts in an interactive mode: - - @nipsys/shadcn-lsd Copyright (C) 2025 Xavier Saliniere - This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. - This is free software, and you are welcome to redistribute it - under certain conditions; type `show c' for details. - -The hypothetical commands `show w' and `show c' should show the appropriate -parts of the General Public License. Of course, your program's commands -might be different; for a GUI interface, you would use an "about box". - - You should also get your employer (if you work as a programmer) or school, -if any, to sign a "copyright disclaimer" for the program, if necessary. -For more information on this, and how to apply and follow the GNU GPL, see -. - - The GNU General Public License does not permit incorporating your program -into proprietary programs. If your program is a subroutine library, you -may consider it more useful to permit linking proprietary applications with -the library. If this is what you want to do, use the GNU Lesser General -Public License instead of this License. But first, please read -. \ No newline at end of file +MIT License + +Copyright (c) 2026 Xavier Saliniere + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/MIGRATION_SUMMARY.md b/MIGRATION_SUMMARY.md deleted file mode 100644 index 551393fe..00000000 --- a/MIGRATION_SUMMARY.md +++ /dev/null @@ -1,298 +0,0 @@ -# Migration Summary: Astro 5.0 → Next.js 16 - -## Overview - -This document summarizes the migration of the `lsd-docs` documentation site from Astro 5.0 to Next.js 16. The migration was completed successfully with all functionality verified and working correctly. - -## Migration Date - -March 11, 2026 - -## What Was Migrated - -### Core Framework -- **From:** Astro 5.0 -- **To:** Next.js 16.1.6 with App Router - -### Key Changes - -#### 1. Project Structure -``` -Before (Astro): -├── src/ -│ ├── pages/ -│ ├── components/ -│ └── layouts/ -├── public/ -└── astro.config.mjs - -After (Next.js): -├── app/ -│ ├── components/ -│ ├── design-tokens/ -│ ├── getting-started/ -│ ├── config/ -│ ├── layout.tsx -│ └── page.tsx -├── public/ -└── next.config.ts -``` - -#### 2. Routing -- **Astro:** File-based routing in `src/pages/` -- **Next.js:** File-based routing in `app/` directory with App Router -- All routes preserved with identical URLs - -#### 3. Components -- Converted all Astro components to React/TSX -- Maintained all functionality and styling -- Preserved component hierarchy and structure - -#### 4. Styling -- Continued using Tailwind CSS 4 -- All styles preserved without changes -- CSS variables and theming maintained - -#### 5. Configuration -- Replaced `astro.config.mjs` with `next.config.ts` -- Configured static export (`output: 'export'`) -- Set custom output directory (`distDir: '../../docs'`) -- Added production optimizations - -## Pages Migrated - -### Documentation Pages (23 total) -- `/` - Home page -- `/components/badge` - Badge component documentation -- `/components/button` - Button component documentation -- `/components/button-group` - ButtonGroup component documentation -- `/components/checkbox` - Checkbox component documentation -- `/components/index` - Components index -- `/components/input` - Input component documentation -- `/components/menubar` - Menubar component documentation -- `/components/progress` - Progress component documentation -- `/components/select` - Select component documentation -- `/components/sidebar` - Sidebar component documentation -- `/components/sonner` - Sonner component documentation -- `/components/switch` - Switch component documentation -- `/components/tabs` - Tabs component documentation -- `/design-tokens/colors` - Colors design tokens -- `/design-tokens/spacing` - Spacing design tokens -- `/design-tokens/typography` - Typography design tokens -- `/getting-started/installation` - Installation guide -- `/getting-started/theming` - Theming guide -- `/getting-started/usage` - Usage guide -- `/_not-found` - 404 page - -## Components Created - -### Layout Components -- `app/layout.tsx` - Root layout with metadata -- `app/components/LayoutWrapper.tsx` - Layout wrapper -- `app/components/SidebarWrapper.tsx` - Sidebar with navigation -- `app/components/Sidebar.tsx` - Sidebar container -- `app/components/SidebarContent.tsx` - Sidebar navigation content -- `app/components/Header.tsx` - Site header -- `app/components/PathProvider.tsx` - Path context provider - -### Documentation Components -- `app/components/docs/ClientOnly.tsx` - Client-side only wrapper -- `app/components/docs/ClientWrapper.tsx` - Client wrapper component -- `app/components/docs/CodeExample.tsx` - Code example display -- `app/components/docs/ComponentPreview.tsx` - Component preview -- `app/components/docs/ThemeToggle.tsx` - Theme toggle button - -### Configuration -- `app/config/navigation.ts` - Navigation structure -- `app/config/site.ts` - Site metadata -- `app/types/navigation.ts` - Navigation types - -## Dependencies - -### Added -- `next@16.1.6` - Next.js framework -- `react@19.2.3` - React library -- `react-dom@19.2.3` - React DOM -- `@phosphor-icons/react@^2.1.10` - Icon library -- `@tailwindcss/postcss@^4` - Tailwind CSS PostCSS plugin -- `tailwindcss@^4` - Tailwind CSS -- `eslint@^9` - ESLint -- `eslint-config-next@16.1.6` - Next.js ESLint config -- `typescript@^5` - TypeScript - -### Removed -- All Astro-specific dependencies -- Astro integrations -- Astro-specific build tools - -## Configuration Changes - -### next.config.ts -```typescript -{ - output: 'export', // Static export - distDir: '../../docs', // Output directory - trailingSlash: true, // Trailing slashes - compress: true, // Compression - images: { unoptimized: true }, // Required for static export - productionBrowserSourceMaps: false, - experimental: { optimizeCss: true }, - compiler: { removeConsole: process.env.NODE_ENV === 'production' } -} -``` - -### package.json Scripts -```json -{ - "dev": "next dev --turbopack", - "build": "next build", - "start": "next start", - "export": "next build", - "preview": "pnpm dlx http-server ../../docs", - "lint": "eslint" -} -``` - -## Performance Optimizations - -### Build Optimizations -- CSS optimization enabled (`optimizeCss: true`) -- Console logs removed in production -- Source maps disabled in production -- Compression enabled - -### Build Results -- **Total build size:** 4.6 MB (down from 252 MB before cleanup) -- **Total files:** 234 -- **Build time:** ~4 seconds -- **All pages:** Static pre-rendered - -### Chunk Sizes -- Largest chunk: 267 KB (fe0beb933eeb1e03.js) -- Second largest: 225 KB (8b72cfc40036c827.js) -- CSS bundle: 75 KB (3ea5ed0fbb2e975d.css) -- Most chunks: 10-30 KB - -## Breaking Changes - -### None -All functionality preserved without breaking changes. The migration was designed to be transparent to end users. - -### Internal Changes -- Component file extensions changed from `.astro` to `.tsx` -- Layout system changed from Astro layouts to Next.js layouts -- Routing system changed from Astro to Next.js App Router -- Build system changed from Astro to Next.js - -## Deployment - -### GitHub Pages -- Site configured to deploy to `docs/` directory -- Static export automatically placed in correct location -- No deployment configuration changes needed - -### Other Platforms -The static export can be deployed to any static hosting service: -- Vercel -- Netlify -- Cloudflare Pages -- AWS S3 + CloudFront - -## Testing - -### Manual Testing -All pages and components were manually tested: -- Navigation works correctly -- All component examples render properly -- Theme switching functions correctly -- Responsive design maintained -- All links work as expected - -### Build Verification -- Clean build completed successfully -- All 23 pages generated -- No build errors or warnings -- Static export verified - -## Files Cleaned Up - -### Removed -- `packages/lsd-docs/.next/` - Next.js build artifacts (17 MB) -- `docs/` - Old build output (252 MB) -- Any temporary or backup files created during migration - -### Preserved -- All source code in `app/` directory -- All configuration files -- All documentation -- All public assets - -## Documentation Updates - -### Updated Files -1. `packages/lsd-docs/README.md` - Complete rewrite with Next.js information -2. `README.md` - Updated with documentation site information - -### New Documentation -- Project structure documentation -- Development workflow documentation -- Deployment instructions -- Tech stack information - -## Migration Notes - -### What Worked Well -- Next.js App Router provided a clean migration path -- Static export configuration was straightforward -- Tailwind CSS integration worked seamlessly -- Component conversion was mostly mechanical - -### Challenges Overcome -- Converting Astro components to React/TSX -- Adapting Astro layouts to Next.js layouts -- Configuring static export with custom output directory -- Maintaining identical URLs and routing - -### Lessons Learned -- Next.js 16 with App Router is well-suited for documentation sites -- Static export is efficient and produces optimized builds -- Turbopack significantly improves development build times -- The migration preserved all functionality without breaking changes - -## Future Considerations - -### Potential Improvements -- Consider adding image optimization for static exports -- Explore incremental static regeneration (ISR) if dynamic content is needed -- Consider adding analytics integration -- Explore adding search functionality - -### Maintenance -- Keep Next.js updated to latest stable version -- Monitor for breaking changes in future Next.js releases -- Regular dependency updates -- Performance monitoring in production - -## Conclusion - -The migration from Astro 5.0 to Next.js 16 was completed successfully. All functionality has been preserved, the build is optimized, and the site is ready for production deployment. The migration provides a solid foundation for future development and improvements. - -## Verification Checklist - -- [x] All pages migrated and working -- [x] All components converted to React/TSX -- [x] Navigation works correctly -- [x] Theme switching functional -- [x] Responsive design maintained -- [x] Build completes successfully -- [x] Static export verified -- [x] Documentation updated -- [x] Temporary files cleaned up -- [x] Performance optimizations applied -- [x] Ready for production deployment - ---- - -**Migration completed by:** Kilo Code -**Date:** March 11, 2026 -**Status:** ✅ Complete and verified diff --git a/README.md b/README.md index b31bc048..225bb496 100644 --- a/README.md +++ b/README.md @@ -1,218 +1,185 @@ -# @nipsys/shadcn-lsd +# @nipsys/lsd - Substance over Spectacle -[![license](https://img.shields.io/npm/l/@nipsys/shadcn-lsd.svg)](https://github.com/nipsysdev/shadcn-lsd/blob/main/LICENSE) -[![React](https://img.shields.io/npm/dependency-version/@nipsys/shadcn-lsd/peer/react.svg)](https://react.dev) +Minimalist, accessible UI components following the [Logos Design System](https://guide.logos.co/). Built for React 19+ on top of Radix UI using shadcn/ui. -A React component library implementing the Logos Design System (LSD). Built with Radix UI primitives and Tailwind CSS, following the shadcn/ui patterns. +This component library follows the guidelines defined by the original Logos Design System, prioritising accessibility and content readability over aesthetics. -## Installation +## Documentation +Visit [lsd.nipsys.dev](https://lsd.nipsys.dev) to view the complete documentation and live examples. -```bash -pnpm add @nipsys/shadcn-lsd -``` +## Get Started with LSD -## Usage +Install the latest version of `nipsys/lsd` -### Import Components - -```tsx -import { Dialog, DialogTrigger, DialogContent, Button } from "@nipsys/shadcn-lsd"; +```bash +npm add @nipsys/lsd ``` -### CSS Import +Import the LSD styles, either in CSS or JS/TS: -```tsx -import '@nipsys/shadcn-lsd/css'; +```css +@import "@nipsys/lsd/css"; ``` -Or in a CSS stylesheet: - -```css -@import "@nipsys/shadcn-lsd/css"; +```ts +import '@nipsys/lsd/css' ``` -### Example +Components are now ready to be used: ```tsx -import { Dialog, DialogTrigger, DialogContent, Button } from "@nipsys/shadcn-lsd"; +import { Button, Card, CardContent, CardHeader, CardTitle } from '@nipsys/lsd' function App() { return ( - - - - - -

Dialog content here

- - - ); + + + Card with a button + + + + + + ) } - -export default App; ``` -### Theming +## What's Inside -The library supports light and dark themes out of the box. Add the `dark` class to your root element to enable dark mode: +- **39 components** covering forms, navigation, data display, overlays, and more +- **Radix UI primitives** for accessibility-first behavior +- **5 accent themes** + light/dark modes +- **Documentation with 185+ live examples** -```html - - - -``` +## Monorepo Structure -### Theme Variants +This is a pnpm workspace monorepo containing two packages: -A teal theme variant is also available: +- **`@nipsys/lsd`** - The component library +- **`@nipsys/lsd-docs`** - Next.js documentation site -```html - - - +## Project Structure - - - ``` - -### CSS Variables - -The design system uses CSS custom properties that you can override: - -```css -:root { - /* Core colors */ - --lsd-primary: #000000; - --lsd-primary-foreground: #ffffff; - --lsd-text-primary: #000000; - --lsd-text-secondary: #808080; - --lsd-border: #000000; - --lsd-surface: #ffffff; - - /* Icon colors */ - --lsd-icon-primary: #000000; - --lsd-icon-secondary: #ffffff; - - /* Semantic colors */ - --lsd-destructive: #b91c1c; - --lsd-destructive-text: #cb3939; - --lsd-success: #15803d; - --lsd-success-text: #168440; - --lsd-warning: #f59e0b; - --lsd-warning-text: #d68b09; - --lsd-info: #2563eb; - --lsd-info-text: #2563eb; -} +packages/ +├── lsd/ # Component library +│ ├── src/ +│ │ ├── components/ui/ # LSD Components +│ │ ├── hooks/ # Custom hooks +│ │ ├── lib/ # Utilities (cn(), types) +│ │ └── styles/ # Design tokens (core.css, themes.css) +│ └── package.json +└── lsd-docs/ # Documentation site + ├── app/ + │ ├── components/ # Docs layout components + │ ├── examples/ # 185+ live examples + │ ├── design-tokens/ # Design system docs + │ └── getting-started/ # Installation, theming + ├── e2e/ # Components behavior & accessibility end-to-end testing + └── scripts/ + └── docs-generator/ # Automated TSDoc-based generator ``` -## Components - -| Component | Description | -|-----------|-------------| -| Accordion | Vertically stacked collapsible sections | -| AlertDialog | Modal dialog for critical confirmations | -| Autocomplete | Input with async suggestion fetching | -| Badge | Small label for status or categorization | -| Button | Interactive button with multiple variants | -| ButtonGroup | Grouped buttons with optional separators | -| Card | Container for related content | -| Checkbox | Boolean input control | -| Command | Command palette for keyboard navigation | -| Dialog | Modal overlay for focused content | -| Input | Text input field | -| Label | Form field label | -| Menubar | Horizontal menu bar with dropdown menus | -| Popover | Floating content anchored to trigger | -| Progress | Visual indicator of completion | -| ScrollArea | Custom scrollbar container | -| Select | Dropdown selection input | -| Separator | Visual divider between sections | -| Sheet | Slide-out panel overlay | -| Sidebar | Navigation sidebar component | -| Sonner | Toast notifications | -| Switch | Toggle switch input | -| Tabs | Tabbed content navigation | -| Toggle | Two-state button | -| ToggleGroup | Group of toggle buttons | -| Typography | Text styling components | - ## Development -### Prerequisites - -- Node.js >= 24.0.0 -- pnpm >= 10 - ### Setup ```bash -# Clone the repository -git clone https://github.com/nipsysdev/shadcn-lsd.git -cd shadcn-lsd - -# Install dependencies pnpm install ``` -### Scripts +### Build ```bash -# Build the library +# Build both packages pnpm build -# Run tests +# Build component library only +pnpm lsd:build + +# Build documentation site only +pnpm docs:build +``` + +### Testing + +Note: E2E tests live inside the lsd-docs packages as they are run against the documentation examples pages. + +```bash +# Run all tests pnpm test -# Run tests in watch mode -pnpm test:watch +# LSD-only Unit tests with watch mode +pnpm lsd:test:watch -# Run tests with coverage -pnpm test:coverage +# E2E tests (Playwright) +pnpm docs:test:e2e -# Lint code -pnpm lint +# Test with UI mode +pnpm docs:test:e2e:ui +``` -# Format code -pnpm format +### Documentation Site -# Start documentation site (Next.js) +```bash +# Start dev server pnpm docs:dev -# Build documentation site +# Build for production (static build) pnpm docs:build -# Preview documentation build +# Preview production build pnpm docs:preview ``` -### Documentation Site +### Linting & Formatting (powered by Biome) + +```bash +# Check code +pnpm lint + +# Auto-fix issues +pnpm lint:fix + +# Format code +pnpm format +``` -The documentation site is built with Next.js 16 and uses static site generation. Run `pnpm docs:dev` to start the development server at `http://localhost:3000`. +## AI-generated documentation pages -The documentation is automatically deployed to GitHub Pages via the `docs/` directory. +The documentation site uses an automated generator that extracts metadata from AI-generated TSDoc annotations in component source files, so manual modifications to documentation pages should be avoided. -## Tech Stack +#### Prompt to generate TSDoc and documentation page using an AI agent +Note: Your agent needs to be able to fetch webpages as it will be instructed to get component information from the Radix UI and shadcn/ui documentation sites. -- **React 19** - UI library -- **TypeScript** - Type safety -- **Tailwind CSS 4** - Utility-first styling -- **Radix UI** - Accessible primitives -- **Vite** - Build tooling -- **Vitest** - Testing framework -- **Next.js 16** - Documentation site framework +Prompt: -## Peer Dependencies +```Re-generate the documentation page for the Button component while strictly following the instructions in tsdoc-page-generation.md``` -Make sure your project has these installed: +#### Manually regenerating a documentation page from TSDoc annotations -```json -{ - "react": "^19.2.4", - "react-dom": "^19.2.4" -} +```bash +pnpm docs:generate button ``` +#### Manually regenerating all documentation pages from TSDoc annotations + +```bash +pnpm docs:generate --all +``` + +The generator parses: +- Component props and their types +- Variant and size configurations from CVA +- Accessibility patterns (keyboard, ARIA, focus) +- TSDoc custom tags for documentation sections + +See `tsdoc-page-generation.md` for complete documentation generation guidelines (intended for AI agents, but of course readable by humans too). + +## Contributing + +See [CONTRIBUTING.md](./CONTRIBUTING.md) for contribution guidelines and code of conduct. + ## License -[GPL-3.0-or-later](LICENSE) +MIT diff --git a/biome.json b/biome.json index e4756a44..85efde11 100644 --- a/biome.json +++ b/biome.json @@ -7,7 +7,15 @@ }, "files": { "ignoreUnknown": false, - "includes": ["**", "!docs", "!**/dist", "!**/node_modules", "!**/.next", "!**/coverage"] + "includes": [ + "**", + "!docs", + "!**/dist", + "!**/node_modules", + "!**/.next", + "!**/coverage", + "!**/LICENSE" + ] }, "formatter": { "enabled": true, @@ -94,6 +102,21 @@ } } } + }, + { + "includes": [ + "**/__tests__/**/*.ts", + "**/__tests__/**/*.tsx", + "**/*.test.ts", + "**/*.test.tsx" + ], + "linter": { + "rules": { + "suspicious": { + "noExplicitAny": "off" + } + } + } } ] } diff --git a/index.html b/index.html deleted file mode 100644 index a96845a5..00000000 --- a/index.html +++ /dev/null @@ -1,21 +0,0 @@ - - - - - - src_ui - - - -
- - - diff --git a/lefthook.yml b/lefthook.yml index 0ab4de0f..d7b30ea9 100644 --- a/lefthook.yml +++ b/lefthook.yml @@ -13,9 +13,8 @@ commit-msg: run: pnpm exec commitlint --edit {1} pre-push: - parallel: true commands: - build: - run: pnpm build test: run: pnpm test + build: + run: pnpm build diff --git a/package.json b/package.json index d15b5ad3..9a6cd29a 100644 --- a/package.json +++ b/package.json @@ -1,12 +1,12 @@ { - "name": "@nipsys/shadcn-lsd-monorepo", - "version": "0.2.5", + "name": "@nipsys/lsd-monorepo", + "version": "1.0.0", "private": true, - "description": "Monorepo for the shadcn-lsd component library and documentation", - "license": "GPL-3.0-or-later", + "description": "Monorepo for the @nipsys/lsd component library and documentation", + "license": "MIT", "repository": { "type": "git", - "url": "git+https://github.com/nipsysdev/shadcn-lsd.git" + "url": "git+https://github.com/nipsysdev/lsd.git" }, "author": "Xavier Saliniere ", "engines": { @@ -14,16 +14,25 @@ "pnpm": ">=10" }, "scripts": { - "build": "pnpm --filter @nipsys/shadcn-lsd build", + "build": "pnpm --filter @nipsys/lsd build && pnpm --filter @nipsys/lsd-docs build", + "test": "pnpm --filter @nipsys/lsd test && pnpm --filter @nipsys/lsd-docs test", "lint": "biome check .", "lint:fix": "biome check . --fix", "format": "biome format --write .", - "test": "pnpm --filter @nipsys/shadcn-lsd test", - "test:watch": "pnpm --filter @nipsys/shadcn-lsd test:watch", - "test:coverage": "pnpm --filter @nipsys/shadcn-lsd test:coverage", + "lsd:build": "pnpm --filter @nipsys/lsd build", + "lsd:test": "pnpm --filter @nipsys/lsd test", + "lsd:test:watch": "pnpm --filter @nipsys/lsd test:watch", + "lsd:test:coverage": "pnpm --filter @nipsys/lsd test:coverage", "docs:dev": "pnpm --filter @nipsys/lsd-docs dev", "docs:build": "pnpm --filter @nipsys/lsd-docs build", - "docs:preview": "pnpm --filter @nipsys/lsd-docs preview" + "docs:preview": "pnpm --filter @nipsys/lsd-docs preview", + "docs:generate": "pnpm --filter @nipsys/lsd-docs generate", + "docs:test": "pnpm --filter @nipsys/lsd-docs test", + "docs:test:watch": "pnpm --filter @nipsys/lsd-docs test:watch", + "docs:test:coverage": "pnpm --filter @nipsys/lsd-docs test:coverage", + "docs:test:e2e": "pnpm --filter @nipsys/lsd-docs test:e2e", + "docs:test:e2e:ui": "pnpm --filter @nipsys/lsd-docs test:e2e:ui", + "docs:test:e2e:debug": "pnpm --filter @nipsys/lsd-docs test:e2e:debug" }, "devDependencies": { "@biomejs/biome": "^2.3.14", diff --git a/packages/lsd-docs/LICENSE b/packages/lsd-docs/LICENSE new file mode 100644 index 00000000..9bcf419f --- /dev/null +++ b/packages/lsd-docs/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Xavier Saliniere + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/packages/lsd-docs/README.md b/packages/lsd-docs/README.md deleted file mode 100644 index 59d4f080..00000000 --- a/packages/lsd-docs/README.md +++ /dev/null @@ -1,86 +0,0 @@ -# @nipsys/lsd-docs - -Documentation site for the Logos Design System (LSD) component library. Built with Next.js 16 and React 19. - -## Overview - -This is the documentation site for the `@nipsys/shadcn-lsd` component library. It provides comprehensive documentation, examples, and usage guidelines for all available components. - -## Getting Started - -### Development - -Run the development server: - -```bash -pnpm dev -``` - -Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. - -### Build - -Build the static site for production: - -```bash -pnpm build -``` - -The static files will be output to the `../../docs` directory. - -### Preview - -Preview the production build locally: - -```bash -pnpm preview -``` - -## Project Structure - -``` -packages/lsd-docs/ -├── app/ # Next.js app directory -│ ├── components/ # Documentation pages for components -│ ├── design-tokens/ # Design tokens documentation -│ ├── getting-started/ # Getting started guides -│ ├── config/ # Site configuration -│ └── layout.tsx # Root layout -├── public/ # Static assets -└── next.config.ts # Next.js configuration -``` - -## Tech Stack - -- **Next.js 16** - React framework with App Router -- **React 19** - UI library -- **TypeScript** - Type safety -- **Tailwind CSS 4** - Utility-first styling -- **@nipsys/shadcn-lsd** - Component library - -## Features - -- Static site generation for optimal performance -- Responsive design with mobile-first approach -- Dark mode support -- Interactive component examples -- Comprehensive documentation - -## Deployment - -The site is configured for static export and can be deployed to any static hosting service: - -- **GitHub Pages** - Already configured via `docs/` directory -- **Vercel** - Automatic deployment from git -- **Netlify** - Static site deployment -- **Cloudflare Pages** - Edge deployment - -### GitHub Pages - -The site is configured to deploy to GitHub Pages via the `docs/` directory. The build output is automatically placed in the correct location. - -## Learn More - -- [Next.js Documentation](https://nextjs.org/docs) - Learn about Next.js features and API -- [React Documentation](https://react.dev) - Learn about React -- [Tailwind CSS Documentation](https://tailwindcss.com/docs) - Learn about Tailwind CSS diff --git a/packages/lsd-docs/SEARCH_REVIEW.md b/packages/lsd-docs/SEARCH_REVIEW.md deleted file mode 100644 index 8a39b099..00000000 --- a/packages/lsd-docs/SEARCH_REVIEW.md +++ /dev/null @@ -1,491 +0,0 @@ -# Search Feature Review - Fuse.js Implementation - -## Current Implementation Analysis - -### Overview -The search feature is implemented in [`packages/lsd-docs/app/components/docs/Search.tsx`](packages/lsd-docs/app/components/docs/Search.tsx) using Fuse.js v7.1.0. It provides a command palette interface for searching documentation navigation items. - -### How It Works - -1. **Search Index Building** (lines 32-63) - - Flattens `navItems` from navigation config into a searchable array - - Includes: `id`, `title`, `url`, `category`, and `icon` - - Processes both top-level items and subItems - -2. **Fuse.js Configuration** (lines 66-76) - ```typescript - { - keys: [ - { name: 'title', weight: 2.0 }, - { name: 'category', weight: 1.0 }, - { name: 'description', weight: 1.0 }, - ], - threshold: 0.3, - includeScore: true, - } - ``` - -3. **Search Results** (lines 79-84) - - Returns all items when query is empty - - Uses Fuse.js to filter when query is provided - -4. **Grouping** (lines 87-99) - - Groups results into "Components" and "Pages" - - Hardcoded grouping logic - -5. **Keyboard Shortcuts** (lines 102-116) - - `Cmd/Ctrl + K` to toggle search dialog - - `/` to open search when closed - ---- - -## Issues Found - -### 🔴 Critical Issues - -1. **Missing Description Field** - - Fuse.js config searches for `description` field (weight 1.0) - - Search index never includes descriptions - - This field is effectively dead code - -2. **Unused Keywords Field** - - `SearchItem` interface has `keywords?: string[]` field - - Never populated in search index - - Not included in Fuse.js keys configuration - -### 🟡 Performance Issues - -3. **No Result Limiting** - - Returns all matching results - - For large documentation sites, this could be overwhelming - - No pagination or "show more" functionality - -4. **Re-indexing on Every Render** - - `searchIndex` is memoized but still recalculates if navItems changes - - Could be pre-built and cached - -### 🟠 UX Issues - -5. **Limited Search Scope** - - Only searches navigation items (titles and categories) - - Cannot search actual page content - - Users can't find content within documentation pages - -6. **No Match Highlighting** - - Users can't see which parts of the text matched their query - - No visual feedback on why results are ranked as they are - -7. **Suboptimal Grouping** - - Hardcoded grouping into "Components" and "Pages" - - Loses original navigation structure (Forms, Navigation, Feedback, etc.) - - All components lumped together regardless of category - -8. **No Search History** - - No recent searches - - No frequently accessed pages - - No "quick access" section - -9. **Empty State Shows All Items** - - When query is empty, shows all navigation items - - Could be overwhelming for large documentation sites - - Better to show "recent" or "popular" items - -10. **No Fuzzy Search Tuning** - - Threshold of 0.3 is moderate but not optimized - - No distance or location settings - - No minMatchCharLength to prevent searching single characters - ---- - -## Improvement Recommendations - -### Priority 1: Critical Fixes - -#### 1.1 Fix Description Field -**Issue:** Description field is searched but never populated. - -**Solution:** Add descriptions to navigation config or remove from search. - -```typescript -// In navigation.ts, add descriptions: -{ - title: 'Button', - url: '/components/button', - description: 'Interactive button component with multiple variants and sizes', -} - -// Or remove from Fuse.js config if not needed: -keys: [ - { name: 'title', weight: 2.0 }, - { name: 'category', weight: 1.0 }, - // Remove description if not used -], -``` - -#### 1.2 Implement Keywords Field -**Issue:** Keywords field exists but is unused. - -**Solution:** Add keywords to navigation config and include in search. - -```typescript -// In navigation.ts: -{ - title: 'Button', - url: '/components/button', - keywords: ['click', 'action', 'submit', 'cta', 'interactive'], -} - -// In Search.tsx, update Fuse.js config: -keys: [ - { name: 'title', weight: 2.0 }, - { name: 'keywords', weight: 1.5 }, - { name: 'category', weight: 1.0 }, - { name: 'description', weight: 1.0 }, -], -``` - -### Priority 2: Performance Improvements - -#### 2.1 Add Result Limiting -**Issue:** Returns all matching results, could be overwhelming. - -**Solution:** Limit results and add "show more" functionality. - -```typescript -const results = useMemo(() => { - if (!query.trim()) { - return searchIndex.slice(0, 10); // Limit empty state - } - return fuse.search(query, { limit: 20 }).map(result => result.item); -}, [query, fuse, searchIndex]); -``` - -#### 2.2 Pre-build Search Index -**Issue:** Search index is built on every render (though memoized). - -**Solution:** Build index at build time and load as JSON. - -```typescript -// Create a build script to generate search-index.json -// Then load it in the component: -import searchIndexData from '@/data/search-index.json'; - -const searchIndex = useMemo(() => searchIndexData, []); -``` - -#### 2.3 Optimize Fuse.js Configuration -**Issue:** Default settings not optimized for documentation search. - -**Solution:** Tune Fuse.js for better performance and relevance. - -```typescript -const fuse = useMemo(() => { - return new Fuse(searchIndex, { - keys: [ - { name: 'title', weight: 2.0 }, - { name: 'keywords', weight: 1.5 }, - { name: 'category', weight: 1.0 }, - { name: 'description', weight: 1.0 }, - ], - threshold: 0.4, // Slightly more permissive - distance: 100, // Match within 100 characters - minMatchCharLength: 2, // Don't search single characters - includeScore: true, - includeMatches: true, // For highlighting - shouldSort: true, - ignoreLocation: true, // Better for multi-word searches - }); -}, [searchIndex]); -``` - -### Priority 3: UX Enhancements - -#### 3.1 Preserve Original Navigation Structure -**Issue:** Hardcoded grouping loses original structure. - -**Solution:** Use original category names from navigation. - -```typescript -const groupedResults = useMemo(() => { - const groups: Record = {}; - - results.forEach(item => { - const groupKey = item.category; - if (!groups[groupKey]) { - groups[groupKey] = []; - } - groups[groupKey].push(item); - }); - - return groups; -}, [results]); -``` - -#### 3.2 Add Match Highlighting -**Issue:** Users can't see what matched their query. - -**Solution:** Highlight matched text in results. - -```typescript -const highlightMatch = (text: string, matches: any[]) => { - if (!matches || matches.length === 0) return text; - - let highlightedText = text; - matches.forEach(match => { - const { indices } = match; - indices.forEach(([start, end]: [number, number]) => { - const before = highlightedText.slice(0, start); - const matchText = highlightedText.slice(start, end + 1); - const after = highlightedText.slice(end + 1); - highlightedText = `${before}${matchText}${after}`; - }); - }); - - return highlightedText; -}; - -// In CommandItem: - - - -``` - -#### 3.3 Add Search History -**Issue:** No way to see recent searches. - -**Solution:** Store recent searches in localStorage. - -```typescript -const [recentSearches, setRecentSearches] = useState([]); - -useEffect(() => { - const stored = localStorage.getItem('recent-searches'); - if (stored) { - setRecentSearches(JSON.parse(stored)); - } -}, []); - -const handleSearch = (query: string) => { - if (query.trim()) { - const updated = [query, ...recentSearches.filter(s => s !== query)].slice(0, 5); - setRecentSearches(updated); - localStorage.setItem('recent-searches', JSON.stringify(updated)); - } -}; -``` - -#### 3.4 Add "Recent" and "Popular" Sections -**Issue:** Empty state shows all items, which is overwhelming. - -**Solution:** Show recent searches and popular pages when query is empty. - -```typescript -const popularPages = useMemo(() => { - // Could be hardcoded or tracked via analytics - return searchIndex.filter(item => - ['/components/button', '/components/input', '/getting-started/installation'].includes(item.url) - ); -}, [searchIndex]); - -// In render: -{!query.trim() && ( - <> - {recentSearches.length > 0 && ( - - {recentSearches.map(search => ( - setQuery(search)}> - - {search} - - ))} - - )} - - {popularPages.map(item => ( - handleSelect(item.url)}> - {item.title} - - ))} - - -)} -``` - -#### 3.5 Add Keyboard Navigation Improvements -**Issue:** Basic keyboard navigation but could be enhanced. - -**Solution:** Add more keyboard shortcuts and improve UX. - -```typescript -useEffect(() => { - const handleKeyDown = (e: KeyboardEvent) => { - // Cmd/Ctrl + K to toggle - if ((e.metaKey || e.ctrlKey) && e.key === 'k') { - e.preventDefault(); - setOpen(prev => !prev); - } - - // / to open when not in input - if (e.key === '/' && !open && document.activeElement?.tagName !== 'INPUT') { - e.preventDefault(); - setOpen(true); - } - - // Escape to close - if (e.key === 'Escape' && open) { - setOpen(false); - setQuery(''); - } - - // Arrow keys for navigation (handled by Command component) - }; - - document.addEventListener('keydown', handleKeyDown); - return () => document.removeEventListener('keydown', handleKeyDown); -}, [open]); -``` - -### Priority 4: Advanced Features - -#### 4.1 Full-Text Search -**Issue:** Only searches navigation, not page content. - -**Solution:** Index page content for full-text search. - -```typescript -// Build script to extract content from MDX files -// Generate search index with page content -const searchIndex = [ - { - id: '/components/button', - title: 'Button', - url: '/components/button', - category: 'Components', - content: 'The Button component provides interactive actions...', - keywords: ['click', 'action', 'submit'], - }, - // ... -]; -``` - -#### 4.2 Search Analytics -**Issue:** No insight into what users are searching for. - -**Solution:** Track search queries and results. - -```typescript -const handleSearch = (query: string) => { - // Track search query - if (typeof window !== 'undefined' && window.gtag) { - window.gtag('event', 'search', { - search_term: query, - results_count: results.length, - }); - } -}; -``` - -#### 4.3 Search Suggestions -**Issue:** No autocomplete or suggestions. - -**Solution:** Add search suggestions based on popular queries. - -```typescript -const suggestions = useMemo(() => { - if (query.length < 2) return []; - return fuse.search(query, { limit: 5 }).map(r => r.item.title); -}, [query, fuse]); -``` - -#### 4.4 Debounce Search -**Issue:** Search runs on every keystroke. - -**Solution:** Debounce search for better performance. - -```typescript -import { useDebouncedValue } from '@/hooks/useDebouncedValue'; - -const [query, setQuery] = useState(''); -const debouncedQuery = useDebouncedValue(query, 150); - -const results = useMemo(() => { - if (!debouncedQuery.trim()) { - return searchIndex; - } - return fuse.search(debouncedQuery).map(result => result.item); -}, [debouncedQuery, fuse, searchIndex]); -``` - ---- - -## Implementation Priority - -### Phase 1: Critical Fixes (1-2 hours) -1. Fix description field issue -2. Implement keywords field -3. Add result limiting - -### Phase 2: Performance (2-3 hours) -4. Optimize Fuse.js configuration -5. Pre-build search index (optional, for large sites) - -### Phase 3: UX Enhancements (3-4 hours) -6. Preserve original navigation structure -7. Add match highlighting -8. Add search history -9. Add "Recent" and "Popular" sections - -### Phase 4: Advanced Features (5-8 hours) -10. Full-text search (requires build script) -11. Search analytics -12. Search suggestions -13. Debounce search - ---- - -## Testing Recommendations - -1. **Performance Testing** - - Test with 100+ navigation items - - Measure search latency - - Test on mobile devices - -2. **UX Testing** - - Test keyboard navigation - - Test with various query lengths - - Test with typos and fuzzy matching - -3. **Accessibility Testing** - - Test with screen readers - - Test keyboard-only navigation - - Test with high contrast mode - ---- - -## Conclusion - -The current search implementation is functional but has several issues that limit its effectiveness: - -**Strengths:** -- Clean integration with Command component -- Good keyboard shortcuts -- Simple and maintainable code - -**Weaknesses:** -- Missing description field (bug) -- Unused keywords field -- Limited search scope -- No match highlighting -- Suboptimal grouping -- No search history - -**Recommended Actions:** -1. Fix critical bugs (description, keywords) -2. Add result limiting for better UX -3. Preserve original navigation structure -4. Add match highlighting for better feedback -5. Consider full-text search for comprehensive coverage - -The improvements can be implemented incrementally, starting with critical fixes and moving to more advanced features as needed. diff --git a/packages/shadcn-lsd/src/__tests__/setup.ts b/packages/lsd-docs/__tests__/setup.ts similarity index 100% rename from packages/shadcn-lsd/src/__tests__/setup.ts rename to packages/lsd-docs/__tests__/setup.ts diff --git a/packages/lsd-docs/app/components/Header.tsx b/packages/lsd-docs/app/components/Header.tsx index bb925e60..0f43107c 100644 --- a/packages/lsd-docs/app/components/Header.tsx +++ b/packages/lsd-docs/app/components/Header.tsx @@ -1,6 +1,6 @@ 'use client'; -import { Button, SidebarTrigger } from '@nipsys/shadcn-lsd'; +import { Button, SidebarTrigger } from '@nipsys/lsd'; import { GithubLogoIcon, MagnifyingGlassIcon } from '@phosphor-icons/react'; import Link from 'next/link'; import { FontToggle } from './docs/FontToggle'; @@ -42,11 +42,7 @@ export default function Header({ className }: HeaderProps) { - - - - ) + return }`} /> - -

- ButtonGroup supports horizontal and vertical orientations for different layout needs. -

+ + + The simplest form of the component with default styling. + - Horizontal Orientation - Buttons arranged in a row (default) + Horizontal - + + + + + + Component variants for different visual styles and use cases. + - Vertical Orientation - Buttons arranged in a column + Filled Buttons - + - - - -

- Advanced features including separators, text labels, and integration with other - components. -

- - Button Group Example - Different button group configurations + Outlined Buttons - + + + + + + Additional features and capabilities of the component. + - With Different Button Variants - Mix different button variants within the same group + Vertical - + + + + + + + + + + {['ButtonGroup', '├── ButtonGroupText', '└── ButtonGroupSeparator']} + -

All available props for the ButtonGroup components.

- -
- - - orientation - Orientation of the button group - - -

- Type: 'horizontal' | 'vertical' -

-

- Default: 'horizontal' -

-

- Controls whether buttons are arranged in a row or column -

- - +
+ + ButtonGroup + +
+ + + orientation + + Arrangement direction of buttons within the group. + + + + + Type: "horizontal" | "vertical" + + + Options: horizontal, vertical + + + Optional + + + + + + groupLabel + + Accessible label for screen readers identifying the button group's purpose. + + + + + Type: string + + + +
+
+ +
+ + ButtonGroupText + +
+ + + asChild + + Merges attributes with child element instead of rendering as container. + + + + + Type: boolean + + + Default: false + + + Optional + + + +
+ + + The component follows accessibility best practices for screen readers and keyboard + navigation. + + + + + Keyboard Navigation + Keyboard shortcuts and navigation + + + + • Tab - Navigate through buttons in the group + + + • Arrow keys - Navigate through buttons when arranged + + + + + + ARIA Attributes + Proper ARIA attributes for screen readers + + + + • Uses <fieldset> element with <legend> for semantic grouping + + + • groupLabel prop provides required accessible name for screen readers + + + + + + Focus States + Visible focus indicators for keyboard users + + + + • Focus moves through buttons sequentially. Focused button receives visible focus + indicator. + + + + (null); - const buttonSizesIframeRef = useRef(null); - const buttonIconsIframeRef = useRef(null); - const buttonLoadingIframeRef = useRef(null); - const buttonFullWidthIframeRef = useRef(null); - const buttonDisabledIframeRef = useRef(null); - const buttonAsChildIframeRef = useRef(null); + const ButtonAsChildIframeRef = useRef(null); + const ButtonBasicIframeRef = useRef(null); + const ButtonDestructiveIframeRef = useRef(null); + const ButtonDestructiveRoundedIframeRef = useRef(null); + const ButtonDisabledIframeRef = useRef(null); + const ButtonFilledIframeRef = useRef(null); + const ButtonFilledRoundedIframeRef = useRef(null); + const ButtonFullWidthIframeRef = useRef(null); + const ButtonGhostIframeRef = useRef(null); + const ButtonGhostRoundedIframeRef = useRef(null); + const ButtonIconsIframeRef = useRef(null); + const ButtonLinkIframeRef = useRef(null); + const ButtonLoadingIframeRef = useRef(null); + const ButtonOutlinedIframeRef = useRef(null); + const ButtonOutlinedRoundedIframeRef = useRef(null); + const ButtonSizesIframeRef = useRef(null); + const ButtonSuccessIframeRef = useRef(null); + const ButtonSuccessRoundedIframeRef = useRef(null); useSendThemeToIframes( - buttonVariantsIframeRef, - buttonSizesIframeRef, - buttonIconsIframeRef, - buttonLoadingIframeRef, - buttonFullWidthIframeRef, - buttonDisabledIframeRef, - buttonAsChildIframeRef + ButtonAsChildIframeRef, + ButtonBasicIframeRef, + ButtonDestructiveIframeRef, + ButtonDestructiveRoundedIframeRef, + ButtonDisabledIframeRef, + ButtonFilledIframeRef, + ButtonFilledRoundedIframeRef, + ButtonFullWidthIframeRef, + ButtonGhostIframeRef, + ButtonGhostRoundedIframeRef, + ButtonIconsIframeRef, + ButtonLinkIframeRef, + ButtonLoadingIframeRef, + ButtonOutlinedIframeRef, + ButtonOutlinedRoundedIframeRef, + ButtonSizesIframeRef, + ButtonSuccessIframeRef, + ButtonSuccessRoundedIframeRef ); return ( -

- Buttons are interactive elements that trigger actions or navigate users to different - locations. They are the primary way users interact with your application. -

+ + Interactive button component with multiple visual variants including filled, outlined, + and rounded styles. Supports loading states, disabled states, and flexible composition + using Radix Slot. + -

Import the Button component from LSD:

+ Import the Button component from LSD: Click me + return - - - ) +export default function MyComponent() { + return
}`} /> - - - The Form component is composed of several sub-components that work together: - - -
- - - Form - Form provider wrapper - - - - Wraps your form with the FormProvider from react-hook-form, enabling context - access for all form components. - - - - - - - FormField - Connects form control to UI - - - - Links a form field to the react-hook-form controller using the render prop pattern - for maximum flexibility. - - - - - - - FormItem - Field container wrapper - - - - Provides the context for each form field, automatically generating unique IDs and - managing spacing. - - - - - - - FormLabel - Accessible label for field - - - - Renders an accessible label that automatically associates with the form control - and changes color on error. - - - - - - - FormControl - Form control wrapper - - - - Wraps your actual form input component using Radix UI's Slot component, passing - all necessary attributes for accessibility. - - - - - - - FormDescription - Helper text for field - - - - Displays additional helper text below the form field to provide context or - guidance to the user. - - - - - - - FormMessage - Error or success message - - - - Displays validation error messages (or custom messages) when a field has errors, - styled with destructive colors. - - - - - - - useFormField - Custom hook for form fields - - - - Provides access to field state, IDs, and form context for custom form field - implementations. - - - -
- - - + - A simple form with Input components and descriptions. + The simplest form of the component with default styling. - Basic Form - Simple form with basic fields + Basic - + - + - Form with comprehensive validation using react-hook-form rules. + Additional features and capabilities of the component. - Validation Form - Form with validation rules and error handling + Validation - + - - - - - Form showing integration with various LSD components like Select, Switch, and Checkbox. - - - Form with Multiple Components - - Integration with Input, Select, Switch, and Checkbox - + With Other Components - + - - All available props for the Form components. - -
- - - Form - Form provider component - - - - Type: FormProvider from react-hook-form - - - Props: All methods from useForm() - - - Accepts the entire form object returned by useForm({'{...}'}) via spread operator. - - - - - - - FormField - Form field connector - - - - control: Control (required) - - - name: string (required) - - - render: (field, fieldState, formState) → ReactNode - (required) - - - Use the rules prop to pass validation rules to the controller. - - - - - - - FormItem - Form field container - - - - Type: HTMLDivAttributes - - - Props: ...props - - - Accepts all standard HTML div attributes. Styled with CSS Grid for proper spacing. - - - - - - - FormLabel - Form field label - - - - Type: LabelProps (Radix UI Label) - - - Props: ...props - - - Automatically receives htmlFor, data-error aria attributes. Supports all Label - variants and sizes. - - - - - - - FormControl - Form control wrapper - - - - Type: SlotProps (Radix UI Slot) - - - Props: ...props - - - Automatically applies id, aria-describedby, aria-invalid attributes to children. - - - - - - - FormDescription - Helper text component - - - - Type: HTMLParagraphAttributes - - - Props: ...props - - - Automatically receives id attribute. Styled with muted foreground color and label - typography. - - - - - - - FormMessage - Error message component - - - - Type: HTMLParagraphAttributes - - - Props: children?: ReactNode, ...props - - - Automatically receives id attribute. Renders null if no error exists. - - - -
+ + + + + {[ + 'Form', + '└── FormField', + ' └── FormItem', + '├── FormLabel', + '├── FormControl', + '├── FormDescription', + '└── FormMessage', + ]} + + + - The Form component follows accessibility best practices with full ARIA support. + The component follows accessibility best practices for screen readers and keyboard + navigation. - Semantic Markup - Proper HTML structure for accessibility + Keyboard Navigation + Keyboard shortcuts and navigation - - Labels are automatically associated with form controls using htmlFor + • Tab - Navigate through form fields - - Form controls receive proper id attributes generated by FormItem + • Enter - Submit form when on submit button - - Helper and error text are linked via aria-describedby - - - - Error states are indicated with aria-invalid="true" + • Space - Toggle checkboxes and radio buttons - - Keyboard Navigation - Full keyboard support + ARIA Attributes + Proper ARIA attributes for screen readers - - Tab - Navigate through form fields + • aria-invalid - Indicates invalid form fields - - Shift + Tab - Navigate to previous form field + • aria-describedby - Links field to description or error messages - - Enter - Submit form when in a form - - - All nested LSD components (Input, Select, Checkbox, Switch) support their full - keyboard navigation within the form context. + • aria-labelledby or aria-label - Provides accessible labels - - ARIA Attributes - Automatic ARIA attribute management + Focus States + Visible focus indicators for keyboard users - - aria-describedby - Links form control to helper and error text - - - - aria-invalid - Indicates field has validation errors - - - - data-error - Data attribute for styling error states - - - These attributes are automatically managed by the Form components, but you can add - additional ARIA attributes as needed. + • Follows standard HTML form focus behavior. Focus moves through fields in document + order when using Tab. Invalid fields receive focus when form validation fails. - diff --git a/packages/lsd-docs/app/components/input-group/page.tsx b/packages/lsd-docs/app/components/input-group/page.tsx index 3e31f01c..8b472480 100644 --- a/packages/lsd-docs/app/components/input-group/page.tsx +++ b/packages/lsd-docs/app/components/input-group/page.tsx @@ -1,14 +1,8 @@ 'use client'; -import { - Card, - CardContent, - CardDescription, - CardHeader, - CardTitle, - Typography, -} from '@nipsys/shadcn-lsd'; +import { Card, CardContent, CardDescription, CardHeader, CardTitle, Typography } from '@nipsys/lsd'; import { useRef } from 'react'; +import { CodeBlock } from '@/components/docs/CodeBlock'; import { CodeExample } from '@/components/docs/CodeExample'; import { DocsLayout } from '@/components/docs/DocsLayout'; import { IframeExample } from '@/components/docs/IframeExample'; @@ -17,114 +11,110 @@ import { PageHeader } from '@/components/docs/PageHeader'; import { PageNavigation } from '@/components/docs/PageNavigation'; import { PageSection } from '@/components/docs/PageSection'; import { useSendThemeToIframes } from '@/components/docs/useSendIframes'; -import { CODE as InputGroupAlignmentCODE } from '@/examples/input-group/alignment/page'; -import { CODE as InputGroupBasicCODE } from '@/examples/input-group/basic/page'; -import { CODE as InputGroupDisabledCODE } from '@/examples/input-group/disabled/page'; -import { CODE as InputGroupSizesCODE } from '@/examples/input-group/sizes/page'; -import { CODE as InputGroupWithIconsCODE } from '@/examples/input-group/with-icons/page'; +import { + CODE as InputGroupAlignmentCODE, + SIZE as InputGroupAlignmentSIZE, +} from '@/examples/input-group/alignment/page'; +import { + CODE as InputGroupBasicCODE, + SIZE as InputGroupBasicSIZE, +} from '@/examples/input-group/basic/page'; +import { + CODE as InputGroupDisabledCODE, + SIZE as InputGroupDisabledSIZE, +} from '@/examples/input-group/disabled/page'; +import { + CODE as InputGroupSizesCODE, + SIZE as InputGroupSizesSIZE, +} from '@/examples/input-group/sizes/page'; +import { + CODE as InputGroupWithIconsCODE, + SIZE as InputGroupWithIconsSIZE, +} from '@/examples/input-group/with-icons/page'; export default function InputGroupPage() { - const inputGroupAlignmentIframeRef = useRef(null); - const inputGroupSizesIframeRef = useRef(null); - const inputGroupBasicIframeRef = useRef(null); - const inputGroupWithIconsIframeRef = useRef(null); - const inputGroupDisabledIframeRef = useRef(null); + const InputGroupAlignmentIframeRef = useRef(null); + const InputGroupBasicIframeRef = useRef(null); + const InputGroupDisabledIframeRef = useRef(null); + const InputGroupSizesIframeRef = useRef(null); + const InputGroupWithIconsIframeRef = useRef(null); useSendThemeToIframes( - inputGroupAlignmentIframeRef, - inputGroupSizesIframeRef, - inputGroupBasicIframeRef, - inputGroupWithIconsIframeRef, - inputGroupDisabledIframeRef + InputGroupAlignmentIframeRef, + InputGroupBasicIframeRef, + InputGroupDisabledIframeRef, + InputGroupSizesIframeRef, + InputGroupWithIconsIframeRef ); + return ( - InputGroup is a comprehensive component system that allows you to create sophisticated - input layouts by combining inputs with addons, buttons, and text elements. It provides a - flexible way to build forms with prefixes, suffixes, action buttons, and various input - types while maintaining consistent spacing and alignment. + Combines input fields with buttons or text elements into a single visual group. Provides + size context to children and handles focus states and error styling across the group. - Import all InputGroup components from LSD: + Import the InputGroup component from LSD: - - $ - - - - ); + return }`} /> - + - InputGroupAddon provides two alignment options for positioning addons relative to the - input. + The simplest form of the component with default styling. - Alignment Options - Two alignment options for addon positioning + Basic - + - InputGroup supports three size variants that automatically scale all child components - including inputs, buttons, and text. The size is controlled at the InputGroup level and - inherited by all children. + Component sizes for different contexts and visual hierarchy. - InputGroup Sizes - Three size variants for the entire InputGroup + Sizes @@ -133,209 +123,209 @@ export default function MyComponent() { - Additional capabilities including basic usage patterns, icon integration, and disabled - states. + Additional features and capabilities of the component. - Basic Usage - Fundamental InputGroup patterns + Alignment - + - - With Icons - Enhance inputs with Phosphor icons + Disabled - + - - Disabled States - Disabled inputs and buttons with proper styling + With Icons - + - - - Complete prop documentation for all InputGroup components. - - -
- - - InputGroup - Main container component - - - - Type: HTML div attributes - - - size: 'sm' | 'md' | 'lg' - - - Default: 'md' - - - Controls the size of the entire InputGroup and all child components. The size is - automatically inherited by InputGroupInput, InputGroupButton, InputGroupText, and - InputGroupAddon components. - - - - - - - InputGroupAddon - Container for addons and buttons - - - - Type: HTML div attributes - - - align: 'inline-start' | 'inline-end' - - - Default: 'inline-start' - - - Controls the positioning of the addon relative to the input. 'inline-start' - positions the addon before the input, 'inline-end' positions it after the input. - - - + + + + + {[ + 'InputGroup', + '├── InputGroupInput', + '├── InputGroupAddon', + '├── InputGroupButton', + '└── InputGroupText', + ]} + + + + - - - InputGroupButton - Button component for input groups - - - - Type: HTML button attributes - - - variant: 'text' | 'icon' - - - size: 'sm' | 'md' | 'lg' - - - type: 'button' | 'submit' | 'reset' - - - Default: variant='text', size=inherited from InputGroup, - type='button' - - - Button styled specifically for input groups. The 'text' variant renders as a ghost - button, while 'icon' variant renders as a ghost-rounded button with square sizing. - Size is inherited from the parent InputGroup but can be overridden. - - - + +
+ + InputGroup + +
+ + + size + Size variant for the input group. + + + + Type: InputGroupSize + + + Options: sm, md, lg + + + Optional + + + +
+
- - - InputGroupInput - Input field component - - - - Type: HTML input attributes (without size) - - - Default: undefined - - - Standard HTML input with size prop omitted to prevent conflicts. Supports all - standard input attributes like placeholder, disabled, type, etc. - - - +
+ + InputGroupAddon + +
+ + + align + Alignment of the addon element. + + + + Type: InputGroupAddonAlign + + + Options: inline-start, inline-end + + + Default: 'inline-start' + + + Optional + + + +
+
- - - InputGroupText - Text display component - - - - Type: HTML span attributes - - - Default: undefined - - - Span element styled for displaying text within input groups. Perfect for prefixes, - suffixes, and labels. - - - +
+ + InputGroupButton + +
+ + + variant + Visual style variant for button. + + + + Type: InputGroupButtonVariant + + + Options: text, icon + + + Default: 'text' + + + Optional + + + + + + size + Size variant for button. + + + + Type: InputGroupButtonSize + + + Options: sm, md, lg + + + Optional + + + + + + type + Button type attribute. + + + + Type: "button" | "submit" | "reset" + + + Options: button, submit, reset + + + Default: 'button' + + + Optional + + + +
- InputGroup components follow accessibility best practices for screen readers and - keyboard navigation. + The component follows accessibility best practices for screen readers and keyboard + navigation. Keyboard Navigation - - Full keyboard accessibility for all interactive elements - + Keyboard shortcuts and navigation - • Tab - Navigate to the input or button - - - • Shift + Tab - Navigate to previous focusable element + • Tab - Navigate through group items sequentially - • Enter - Submit form (when in a form) - - - • Space or Enter - Activate InputGroupButton + • Enter - Activate focused button within group - ARIA Attributes @@ -343,46 +333,37 @@ export default function MyComponent() { - • Use aria-label for buttons without visible text (icon buttons) + • role="group" identifies the component as a grouping - • Use aria-describedby to link inputs to supporting text - - - • Disabled elements automatically get aria-disabled="true" - - - • InputGroupButton uses proper button semantics for screen readers + • aria-invalid indicates group error state - Focus States Visible focus indicators for keyboard users - - InputGroup components have visible focus states that follow the LSD design system's - focus indicators, ensuring keyboard users can always see which element has focus. - Inputs and buttons maintain distinct focus styles for clarity. + + • Focus is managed across elements within the group. Visual focus indicators appear + on the active element. Group borders change color on focus of any child element. + - - ); } diff --git a/packages/lsd-docs/app/components/input/page.tsx b/packages/lsd-docs/app/components/input/page.tsx index 6103852d..fa9a36fa 100644 --- a/packages/lsd-docs/app/components/input/page.tsx +++ b/packages/lsd-docs/app/components/input/page.tsx @@ -1,13 +1,6 @@ 'use client'; -import { - Card, - CardContent, - CardDescription, - CardHeader, - CardTitle, - Typography, -} from '@nipsys/shadcn-lsd'; +import { Card, CardContent, CardDescription, CardHeader, CardTitle, Typography } from '@nipsys/lsd'; import { useRef } from 'react'; import { CodeExample } from '@/components/docs/CodeExample'; import { DocsLayout } from '@/components/docs/DocsLayout'; @@ -17,44 +10,67 @@ import { PageHeader } from '@/components/docs/PageHeader'; import { PageNavigation } from '@/components/docs/PageNavigation'; import { PageSection } from '@/components/docs/PageSection'; import { useSendThemeToIframes } from '@/components/docs/useSendIframes'; -import { CODE as InputDisabledCODE } from '@/examples/input/disabled/page'; -import { CODE as InputErrorCODE } from '@/examples/input/error/page'; -import { CODE as InputLabelCODE } from '@/examples/input/label/page'; -import { CODE as InputSizesCODE } from '@/examples/input/sizes/page'; -import { CODE as InputSupportingTextCODE } from '@/examples/input/supporting-text/page'; -import { CODE as InputTypesCODE } from '@/examples/input/types/page'; -import { CODE as InputVariantsCODE } from '@/examples/input/variants/page'; +import { CODE as InputDefaultCODE, SIZE as InputDefaultSIZE } from '@/examples/input/default/page'; +import { + CODE as InputDisabledCODE, + SIZE as InputDisabledSIZE, +} from '@/examples/input/disabled/page'; +import { CODE as InputErrorCODE, SIZE as InputErrorSIZE } from '@/examples/input/error/page'; +import { CODE as InputGhostCODE, SIZE as InputGhostSIZE } from '@/examples/input/ghost/page'; +import { CODE as InputLabelCODE, SIZE as InputLabelSIZE } from '@/examples/input/label/page'; +import { + CODE as InputOutlinedCODE, + SIZE as InputOutlinedSIZE, +} from '@/examples/input/outlined/page'; +import { CODE as InputSizesCODE, SIZE as InputSizesSIZE } from '@/examples/input/sizes/page'; +import { + CODE as InputSupportingTextCODE, + SIZE as InputSupportingTextSIZE, +} from '@/examples/input/supporting-text/page'; +import { CODE as InputTypesCODE, SIZE as InputTypesSIZE } from '@/examples/input/types/page'; +import { + CODE as InputUnderlinedCODE, + SIZE as InputUnderlinedSIZE, +} from '@/examples/input/underlined/page'; export default function InputPage() { - const inputVariantsIframeRef = useRef(null); - const inputSizesIframeRef = useRef(null); - const inputLabelIframeRef = useRef(null); - const inputSupportingTextIframeRef = useRef(null); - const inputErrorIframeRef = useRef(null); - const inputTypesIframeRef = useRef(null); - const inputDisabledIframeRef = useRef(null); + const InputDefaultIframeRef = useRef(null); + const InputDisabledIframeRef = useRef(null); + const InputErrorIframeRef = useRef(null); + const InputGhostIframeRef = useRef(null); + const InputLabelIframeRef = useRef(null); + const InputOutlinedIframeRef = useRef(null); + const InputSizesIframeRef = useRef(null); + const InputSupportingTextIframeRef = useRef(null); + const InputTypesIframeRef = useRef(null); + const InputUnderlinedIframeRef = useRef(null); useSendThemeToIframes( - inputVariantsIframeRef, - inputSizesIframeRef, - inputLabelIframeRef, - inputSupportingTextIframeRef, - inputErrorIframeRef, - inputTypesIframeRef, - inputDisabledIframeRef + InputDefaultIframeRef, + InputDisabledIframeRef, + InputErrorIframeRef, + InputGhostIframeRef, + InputLabelIframeRef, + InputOutlinedIframeRef, + InputSizesIframeRef, + InputSupportingTextIframeRef, + InputTypesIframeRef, + InputUnderlinedIframeRef ); + return ( - Inputs are form elements that allow users to enter and edit text. They are the primary - way users provide data to your application, from simple text fields to complex forms. + A styled text input wrapper that provides consistent label, supporting text, and error + states. Supports multiple border variants (underlined, outlined, ghost) and sizes for + different form contexts. @@ -65,54 +81,101 @@ export default function InputPage() { + return }`} /> + + + The simplest form of the component with default styling. + + + + + Default + + + + + + + + - Input comes in two visual variants for different design contexts. + Component variants for different visual styles and use cases. - Border Variants - Choose between outlined and underlined styles + Ghost - + + + + + + Outlined + + + + + + + + + Underlined + + + + - Inputs come in five sizes to fit different contexts and layouts. + Component sizes for different contexts and visual hierarchy. - All Sizes - From extra small to extra large + Sizes @@ -121,279 +184,187 @@ export default function MyComponent() { - Additional features like labels, supporting text, error states, and different input - types. + Additional features and capabilities of the component. - With Label - Add a label to provide context for the input + Disabled - + - - With Supporting Text - - Add helper text below the input for additional guidance - + Error - + - - Error State - Show error state with destructive styling + Label - + - - Input Types - Support for various HTML input types + Supporting Text - + - - Disabled State - Disabled input with reduced opacity + Types - + - All available props for the Input component. - -
- - - variant - The visual style of the input border - - - - Type: BorderVariant - - - Options: outlined, underlined - - - Default: underlined - - - - - - - size - The size of the input - - - - Type: SizeVariant - - - Options: xs, sm, md, lg, xl - - - Default: md - - - - - - - label - Label text displayed above the input - - - - Type: React.ReactNode - - - Default: undefined - - - Optional label for the input field - - - - - - - supportingText - Helper text displayed below the input - - - - Type: React.ReactNode - - - Default: undefined - - - Additional context or guidance for the input - - - - - - - error - Show error state styling - - - - Type: boolean - - - Default: false - - - Changes border color to destructive and supporting text color - - - - - - - type - HTML input type attribute - - - - Type: string - - - Default: text - - - Supports all standard HTML input types - - - - - - - id - Custom ID for the input element - - - - Type: string - - - Default: auto-generated - - - If not provided, a unique ID is automatically generated - - - - - - - className - Additional CSS classes to apply - - - - Type: string - - - Merges with existing input classes - - - - - - - ...props - Standard HTML input attributes - - - - Type:{' '} - React.InputHTMLAttributes<HTMLInputElement> - - - All standard HTML input attributes are supported - - - +
+ + Input + +
+ + + variant + Border visual style variant. + + + + Type: BorderVariant + + + Optional + + + + + + size + Input size variant. + + + + Type: SizeVariant + + + Optional + + + + + + label + Label displayed above the input. + + + + Type: React.ReactNode + + + Optional + + + + + + supportingText + + Supporting text or error message displayed below the input. + + + + + Type: React.ReactNode + + + Optional + + + + + + error + Error state styling with red border. + + + + Type: boolean + + + Optional + + + +
- The Input component follows accessibility best practices. + The component follows accessibility best practices for screen readers and keyboard + navigation. Keyboard Navigation - Inputs are fully keyboard accessible + Keyboard shortcuts and navigation - • Tab - Navigate to the input + • Tab - Navigate to the input - • Shift + Tab - Navigate to previous focusable element + • Shift + Tab - Navigate to previous element - - • Enter - Submit form (when in a form) + + • Standard input keyboard shortcuts for editing (Arrow keys, Home, End, Delete, + Backspace) - ARIA Attributes @@ -401,46 +372,40 @@ export default function MyComponent() { - • Labels are automatically associated with inputs using htmlFor + • aria-invalid - Marks input as having validation errors - • Use aria-invalid when input has errors (automatically handled with - error prop) + • aria-describedby - Links to supporting text or error message - • Use aria-describedby to link to supporting text - - - • Use aria-label for inputs without visible labels + • aria-labelledby - Links to label element - Focus States Visible focus indicators for keyboard users - - Inputs have visible focus states that follow the LSD design system's focus - indicators, ensuring keyboard users can always see which element has focus. + + • Focus is managed natively by browser. Visual focus indicators show when input is + active. Error states have distinct focus indicators to provide clear feedback. + - - ); } diff --git a/packages/lsd-docs/app/components/label/page.tsx b/packages/lsd-docs/app/components/label/page.tsx index bb34f2db..e05f14c1 100644 --- a/packages/lsd-docs/app/components/label/page.tsx +++ b/packages/lsd-docs/app/components/label/page.tsx @@ -1,13 +1,6 @@ 'use client'; -import { - Card, - CardContent, - CardDescription, - CardHeader, - CardTitle, - Typography, -} from '@nipsys/shadcn-lsd'; +import { Card, CardContent, CardDescription, CardHeader, CardTitle, Typography } from '@nipsys/lsd'; import { useRef } from 'react'; import { CodeExample } from '@/components/docs/CodeExample'; import { DocsLayout } from '@/components/docs/DocsLayout'; @@ -17,31 +10,34 @@ import { PageHeader } from '@/components/docs/PageHeader'; import { PageNavigation } from '@/components/docs/PageNavigation'; import { PageSection } from '@/components/docs/PageSection'; import { useSendThemeToIframes } from '@/components/docs/useSendIframes'; -import { CODE as LabelBasicExampleCODE } from '@/examples/label/basic/page'; -import { CODE as LabelSizesExampleCODE } from '@/examples/label/sizes/page'; -import { CODE as LabelVariantsExampleCODE } from '@/examples/label/variants/page'; +import { CODE as LabelBasicCODE, SIZE as LabelBasicSIZE } from '@/examples/label/basic/page'; +import { CODE as LabelSizesCODE, SIZE as LabelSizesSIZE } from '@/examples/label/sizes/page'; +import { + CODE as LabelVariantsCODE, + SIZE as LabelVariantsSIZE, +} from '@/examples/label/variants/page'; export default function LabelPage() { - const labelBasicIframeRef = useRef(null); - const labelVariantsIframeRef = useRef(null); - const labelSizesIframeRef = useRef(null); + const LabelBasicIframeRef = useRef(null); + const LabelSizesIframeRef = useRef(null); + const LabelVariantsIframeRef = useRef(null); - useSendThemeToIframes(labelBasicIframeRef, labelVariantsIframeRef, labelSizesIframeRef); + useSendThemeToIframes(LabelBasicIframeRef, LabelSizesIframeRef, LabelVariantsIframeRef); return ( - The Label component provides accessible labeling for form inputs and other interactive - elements. It automatically associates with form controls using the htmlFor{' '} - attribute, ensuring screen readers can properly describe the relationship between labels - and their associated controls. + Text label component that provides clear identification for form inputs and controls. + Built on Radix UI's Label primitive with support for default and secondary variants and + three size options. Automatically handles accessibility by associating with controls + through htmlFor or nested relationships. @@ -52,15 +48,10 @@ export default function LabelPage() { - - -
- ) + return