reflex-dynoselect


Namereflex-dynoselect JSON
Version 0.1.0 PyPI version JSON
download
home_pageNone
SummaryGeneric and specialized Reflex select components. Users can search for options and create new ones. Includes specialized time zone and language select components in over 100 languages.
upload_time2024-05-13 22:08:35
maintainerNone
docs_urlNone
authorNone
requires_python>=3.8
licenseApache-2.0
keywords reflex reflex-custom-components select timezone time zone locale language language select
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # Dynoselect

Dynoselect is a collection of select components for [Reflex](https://reflex.dev). 
The base component allows users to search for options and create new ones:

<img src="data/demo.gif" height="300px">

In addition, there are specialized components for standard use-cases like time zone and 
language selection. The options listed by them are available in over 100 
languages (and over 400 language variants!) so you don't have to translate them yourself.
Just specify the [IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag) 
you would like to use, e.g. _"de"_ for German (as spoken in Germany) or _"en-GB"_ for 
English (as spoken in the United Kingdom).

There is a special "locale" available for the language select component: Displaying 
each language option in the respective language itself. For this, just specify 
`None` for the `locale` parameter of the component:

<img src="data/language.gif" height="480px">

Selecting one's own time zone is a surprisingly difficult task for most users. 
This has been studied quite extensively in [this Article](https://www.nngroup.com/articles/time-zone-selectors/).
The time zone selection component makes this task as simple as possible.

Not having to select your time zone at all is of course most user-friendly. 
Therefore, the component tries to automatically detect the user's time zone. Manual
selection is only necessary if the result turns out to be incorrect. 

Following the advice given in the above article, the component lists time zones as 
__city, country (UTC offset)__. This is because most people can name a city or country 
representative of their time zone. The offset is given last, because people expect the 
list to be ordered alphabetically and often do not know their offset anyway. It mainly
serves as confirmation. The offset displayed takes into 
account whether daylight saving time is currently in effect in each listed time zone and 
is updated every time the dropdown is opened.

<img src="data/timezone.gif" height="480px">


The following example shows how to use the components within a Reflex project:

```py
import reflex as rx
from reflex_dynoselect import dynoselect, dynotimezone, dynolanguage

options = [
    {"value": "ocean", "label": "Ocean"},
    {"value": "blue", "label": "Blue"},
    {"value": "purple", "label": "Purple"},
    {"value": "green", "label": "Green"},
    {"value": "red", "label": "Red"},
    {"value": "yellow", "label": "Yellow"},
]

class State(rx.State):
    """The app state."""
    pass

def index() -> rx.Component:
    return rx.vstack(
        dynoselect(
            options,
            placeholder="Select a color",
            search_placeholder="Search for a color",
        ),
        dynotimezone(
            "en",
            placeholder="Timezone", 
            search_placeholder="Search timezone..."
        ),        
        dynolanguage(
            "en",
            placeholder="Language", 
            search_placeholder="Search for a language..."
        ),
        align="center",
        spacing="4"
    )

# Add state and page to the app.
app = rx.App()
app.add_page(index)
```

Options are given as a list of dictionaries. Each dictionary must contain a `label`
and a `value` key with strings as values. The `label` is displayed to the user while
the value key can be used for internal identifiers. Optionally, one can provide a 
`keywords` key to include alternative phrases that are included in the search but
not displayed to the user.

The `selected` attribute contains the complete dictionary of the currently selected 
option. In addition to the `value`, `label`, and `keywords` keys, one can add
arbitrary keys to the dictionary to store additional information about an option.

### Parameters
- `options`: A list of dictionaries containing the options. The dictionary
    must contain a `label` and a `value` key with strings as values. The value of the
    `label` key is displayed to the user while the `value` key can be used as internal
    identifier. Optionally, one can provide a `keywords` key to include alternative 
    phrases that are included in the search but not displayed to the user. This is 
    intended to improve the search tolerance so that users can find options even 
    if they enter synonyms. You may provide keywords either as a string or as a list
    of strings. For example, the option
    ```py
    {"value": "ocean", "label": "Ocean", "keywords": ["blue", "water"]}
    ```
    allows to input _"water"_ or _"blue"_ in order to search for the color _Ocean_.

- `default_option`: The default option to select. By default, no option is selected.
- `placeholder`: The placeholder text that is shown when no option is selected.
- `search_placeholder`: The placeholder text for the search input field.
- `size`: Relative size of the component. Allowed values are "1", "2", and "3".
- `weight`: The weight of the text. Allowed values are "none", "light", "regular", 
    "medium", and "bold".
- `radius`: The edge radius of the component. Allowed values are "none", "small", 
    "medium", "large", and "full".
- `height`: The height of the component menu. Can be given as a CSS value like "10rem" 
    or "100%".
- `padding`: The padding around the border of the select menu.
- `indent`: The indentation of the select menu. If "center" is given, the 
    indentation is applied horizontally to both sides and therefore acts as padding. 
    Otherwise, it is applied to one side only and works as indentation.
- `align`: The alignment of the options. Allowed values are "left", "center", and 
    "right".
- `create_option`: The option dictionary to create a new entry. If `create_option` is 
    None, the feature is deactivated. If the option is a dictionary, it specifies the 
    `value` and `label` attributes used for the create option. You may either provide a 
    static text or refer to the current search phrase by using "{}" as placeholder. 
    For example:
    ```py
    dynoselect(
        options,
        placeholder="Select a color",
        search_placeholder="Search for a color",
        create_option=dict(value="custom", label='Create new "{}"'),
    )
    ```
    The `label` given in the example above would be displayed as _Create new "Apple"_ if 
    the search phrase is _"Apple"_. Regarding the `value` key, you can use any value you 
    like.   
- `on_select`: Event handler that is called when the user selects an option. Note
    that the event handler is called even if the user selects the same value as before.
- `icon`: The name of the [lucide icon](https://lucide.dev/icons/) to display.
- `content_props`: Additional properties that are passed on to the 
    [reflex.popover.content](https://reflex.dev/docs/library/overlay/popover/#popovercontent) 
    component used by Dynoselect.
- `root_props`: Additional properties that are passed on to the 
    [reflex.popover.root](https://reflex.dev/docs/library/overlay/popover/#popoverroot) 
    component used by Dynoselect.

#### Additional options for `dynotimezone`:
- `locale`: The locale to display the time zone options in. 

#### Additional options for `dynolanguage`:
- `locale`: The locale to use for the displayed language options. If None, the names 
    of all languages are displayed in the respective languages themselves.
- `only` : Optional iterable with [IETF language tags](https://en.wikipedia.org/wiki/IETF_language_tag) 
    to display. Default is None, so that all available language options are displayed. 
    Example:
    ```py
    dynolanguage(
        placeholder="Language", 
        search_placeholder="Search for a language...",
        only={"de", "en", "en-GB", "es", "fr", "fr-CH"},
    ),
    ```
    This will display options for German (as spoken in Germany), English (as spoken in 
    the United States), English (as spoken in the UK), Spanish (as spoken in Spain), 
    French (as spoken in France), and French (as spoken in Switzerland).

## Installation
The components have been tested without activating [Tailwind](https://tailwindcss.com/) 
explicitly. However, if the component looks strange, you may want to activate it as 
described in the [official documentation](https://reflex.dev/docs/styling/overview/#tailwind).

The components can be installed using the following command:
```bash
pip install reflex-dynoselect
```

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "reflex-dynoselect",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": null,
    "keywords": "reflex, reflex-custom-components, select, timezone, time zone, locale, language, language select",
    "author": null,
    "author_email": "Marcus W\u00f6rner <woernerm@protonmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/34/03/8504bd5938d627a251181a4e7c25b0acf7cca0a0bfe3d18f959a9885b9ab/reflex_dynoselect-0.1.0.tar.gz",
    "platform": null,
    "description": "# Dynoselect\r\n\r\nDynoselect is a collection of select components for [Reflex](https://reflex.dev). \r\nThe base component allows users to search for options and create new ones:\r\n\r\n<img src=\"data/demo.gif\" height=\"300px\">\r\n\r\nIn addition, there are specialized components for standard use-cases like time zone and \r\nlanguage selection. The options listed by them are available in over 100 \r\nlanguages (and over 400 language variants!) so you don't have to translate them yourself.\r\nJust specify the [IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag) \r\nyou would like to use, e.g. _\"de\"_ for German (as spoken in Germany) or _\"en-GB\"_ for \r\nEnglish (as spoken in the United Kingdom).\r\n\r\nThere is a special \"locale\" available for the language select component: Displaying \r\neach language option in the respective language itself. For this, just specify \r\n`None` for the `locale` parameter of the component:\r\n\r\n<img src=\"data/language.gif\" height=\"480px\">\r\n\r\nSelecting one's own time zone is a surprisingly difficult task for most users. \r\nThis has been studied quite extensively in [this Article](https://www.nngroup.com/articles/time-zone-selectors/).\r\nThe time zone selection component makes this task as simple as possible.\r\n\r\nNot having to select your time zone at all is of course most user-friendly. \r\nTherefore, the component tries to automatically detect the user's time zone. Manual\r\nselection is only necessary if the result turns out to be incorrect. \r\n\r\nFollowing the advice given in the above article, the component lists time zones as \r\n__city, country (UTC offset)__. This is because most people can name a city or country \r\nrepresentative of their time zone. The offset is given last, because people expect the \r\nlist to be ordered alphabetically and often do not know their offset anyway. It mainly\r\nserves as confirmation. The offset displayed takes into \r\naccount whether daylight saving time is currently in effect in each listed time zone and \r\nis updated every time the dropdown is opened.\r\n\r\n<img src=\"data/timezone.gif\" height=\"480px\">\r\n\r\n\r\nThe following example shows how to use the components within a Reflex project:\r\n\r\n```py\r\nimport reflex as rx\r\nfrom reflex_dynoselect import dynoselect, dynotimezone, dynolanguage\r\n\r\noptions = [\r\n    {\"value\": \"ocean\", \"label\": \"Ocean\"},\r\n    {\"value\": \"blue\", \"label\": \"Blue\"},\r\n    {\"value\": \"purple\", \"label\": \"Purple\"},\r\n    {\"value\": \"green\", \"label\": \"Green\"},\r\n    {\"value\": \"red\", \"label\": \"Red\"},\r\n    {\"value\": \"yellow\", \"label\": \"Yellow\"},\r\n]\r\n\r\nclass State(rx.State):\r\n    \"\"\"The app state.\"\"\"\r\n    pass\r\n\r\ndef index() -> rx.Component:\r\n    return rx.vstack(\r\n        dynoselect(\r\n            options,\r\n            placeholder=\"Select a color\",\r\n            search_placeholder=\"Search for a color\",\r\n        ),\r\n        dynotimezone(\r\n            \"en\",\r\n            placeholder=\"Timezone\", \r\n            search_placeholder=\"Search timezone...\"\r\n        ),        \r\n        dynolanguage(\r\n            \"en\",\r\n            placeholder=\"Language\", \r\n            search_placeholder=\"Search for a language...\"\r\n        ),\r\n        align=\"center\",\r\n        spacing=\"4\"\r\n    )\r\n\r\n# Add state and page to the app.\r\napp = rx.App()\r\napp.add_page(index)\r\n```\r\n\r\nOptions are given as a list of dictionaries. Each dictionary must contain a `label`\r\nand a `value` key with strings as values. The `label` is displayed to the user while\r\nthe value key can be used for internal identifiers. Optionally, one can provide a \r\n`keywords` key to include alternative phrases that are included in the search but\r\nnot displayed to the user.\r\n\r\nThe `selected` attribute contains the complete dictionary of the currently selected \r\noption. In addition to the `value`, `label`, and `keywords` keys, one can add\r\narbitrary keys to the dictionary to store additional information about an option.\r\n\r\n### Parameters\r\n- `options`: A list of dictionaries containing the options. The dictionary\r\n    must contain a `label` and a `value` key with strings as values. The value of the\r\n    `label` key is displayed to the user while the `value` key can be used as internal\r\n    identifier. Optionally, one can provide a `keywords` key to include alternative \r\n    phrases that are included in the search but not displayed to the user. This is \r\n    intended to improve the search tolerance so that users can find options even \r\n    if they enter synonyms. You may provide keywords either as a string or as a list\r\n    of strings. For example, the option\r\n    ```py\r\n    {\"value\": \"ocean\", \"label\": \"Ocean\", \"keywords\": [\"blue\", \"water\"]}\r\n    ```\r\n    allows to input _\"water\"_ or _\"blue\"_ in order to search for the color _Ocean_.\r\n\r\n- `default_option`: The default option to select. By default, no option is selected.\r\n- `placeholder`: The placeholder text that is shown when no option is selected.\r\n- `search_placeholder`: The placeholder text for the search input field.\r\n- `size`: Relative size of the component. Allowed values are \"1\", \"2\", and \"3\".\r\n- `weight`: The weight of the text. Allowed values are \"none\", \"light\", \"regular\", \r\n    \"medium\", and \"bold\".\r\n- `radius`: The edge radius of the component. Allowed values are \"none\", \"small\", \r\n    \"medium\", \"large\", and \"full\".\r\n- `height`: The height of the component menu. Can be given as a CSS value like \"10rem\" \r\n    or \"100%\".\r\n- `padding`: The padding around the border of the select menu.\r\n- `indent`: The indentation of the select menu. If \"center\" is given, the \r\n    indentation is applied horizontally to both sides and therefore acts as padding. \r\n    Otherwise, it is applied to one side only and works as indentation.\r\n- `align`: The alignment of the options. Allowed values are \"left\", \"center\", and \r\n    \"right\".\r\n- `create_option`: The option dictionary to create a new entry. If `create_option` is \r\n    None, the feature is deactivated. If the option is a dictionary, it specifies the \r\n    `value` and `label` attributes used for the create option. You may either provide a \r\n    static text or refer to the current search phrase by using \"{}\" as placeholder. \r\n    For example:\r\n    ```py\r\n    dynoselect(\r\n        options,\r\n        placeholder=\"Select a color\",\r\n        search_placeholder=\"Search for a color\",\r\n        create_option=dict(value=\"custom\", label='Create new \"{}\"'),\r\n    )\r\n    ```\r\n    The `label` given in the example above would be displayed as _Create new \"Apple\"_ if \r\n    the search phrase is _\"Apple\"_. Regarding the `value` key, you can use any value you \r\n    like.   \r\n- `on_select`: Event handler that is called when the user selects an option. Note\r\n    that the event handler is called even if the user selects the same value as before.\r\n- `icon`: The name of the [lucide icon](https://lucide.dev/icons/) to display.\r\n- `content_props`: Additional properties that are passed on to the \r\n    [reflex.popover.content](https://reflex.dev/docs/library/overlay/popover/#popovercontent) \r\n    component used by Dynoselect.\r\n- `root_props`: Additional properties that are passed on to the \r\n    [reflex.popover.root](https://reflex.dev/docs/library/overlay/popover/#popoverroot) \r\n    component used by Dynoselect.\r\n\r\n#### Additional options for `dynotimezone`:\r\n- `locale`: The locale to display the time zone options in. \r\n\r\n#### Additional options for `dynolanguage`:\r\n- `locale`: The locale to use for the displayed language options. If None, the names \r\n    of all languages are displayed in the respective languages themselves.\r\n- `only` : Optional iterable with [IETF language tags](https://en.wikipedia.org/wiki/IETF_language_tag) \r\n    to display. Default is None, so that all available language options are displayed. \r\n    Example:\r\n    ```py\r\n    dynolanguage(\r\n        placeholder=\"Language\", \r\n        search_placeholder=\"Search for a language...\",\r\n        only={\"de\", \"en\", \"en-GB\", \"es\", \"fr\", \"fr-CH\"},\r\n    ),\r\n    ```\r\n    This will display options for German (as spoken in Germany), English (as spoken in \r\n    the United States), English (as spoken in the UK), Spanish (as spoken in Spain), \r\n    French (as spoken in France), and French (as spoken in Switzerland).\r\n\r\n## Installation\r\nThe components have been tested without activating [Tailwind](https://tailwindcss.com/) \r\nexplicitly. However, if the component looks strange, you may want to activate it as \r\ndescribed in the [official documentation](https://reflex.dev/docs/styling/overview/#tailwind).\r\n\r\nThe components can be installed using the following command:\r\n```bash\r\npip install reflex-dynoselect\r\n```\r\n",
    "bugtrack_url": null,
    "license": "Apache-2.0",
    "summary": "Generic and specialized Reflex select components. Users can search for options and create new ones. Includes specialized time zone and language select components in over 100 languages.",
    "version": "0.1.0",
    "project_urls": null,
    "split_keywords": [
        "reflex",
        " reflex-custom-components",
        " select",
        " timezone",
        " time zone",
        " locale",
        " language",
        " language select"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "2aad65231700c9948ebd28faa97647a3ea95224d824d2e70719b6f872e09ad12",
                "md5": "e7dbe07a47578fc8ebc06a49c824d314",
                "sha256": "04453db8f3d60da952e62b9a32b6edffeefaccf6972a4d18dbdaca206353f41e"
            },
            "downloads": -1,
            "filename": "reflex_dynoselect-0.1.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "e7dbe07a47578fc8ebc06a49c824d314",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 17318,
            "upload_time": "2024-05-13T22:08:33",
            "upload_time_iso_8601": "2024-05-13T22:08:33.246898Z",
            "url": "https://files.pythonhosted.org/packages/2a/ad/65231700c9948ebd28faa97647a3ea95224d824d2e70719b6f872e09ad12/reflex_dynoselect-0.1.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "34038504bd5938d627a251181a4e7c25b0acf7cca0a0bfe3d18f959a9885b9ab",
                "md5": "d1e1f96923a95c07bc14d3fe3af05f75",
                "sha256": "c2232318ade6d66e3bff8509df6520f1a6f35bbc710b44a02638feb4fcd9cb04"
            },
            "downloads": -1,
            "filename": "reflex_dynoselect-0.1.0.tar.gz",
            "has_sig": false,
            "md5_digest": "d1e1f96923a95c07bc14d3fe3af05f75",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 18445,
            "upload_time": "2024-05-13T22:08:35",
            "upload_time_iso_8601": "2024-05-13T22:08:35.006478Z",
            "url": "https://files.pythonhosted.org/packages/34/03/8504bd5938d627a251181a4e7c25b0acf7cca0a0bfe3d18f959a9885b9ab/reflex_dynoselect-0.1.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-05-13 22:08:35",
    "github": false,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "lcname": "reflex-dynoselect"
}
        
Elapsed time: 0.23671s