insight-ui 1.14.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (151) hide show
  1. insight_ui/THIRD_PARTY_NOTICES.md +48 -0
  2. insight_ui/__init__.py +15 -0
  3. insight_ui/_version.py +24 -0
  4. insight_ui/asset_urls.py +113 -0
  5. insight_ui/brand.py +57 -0
  6. insight_ui/cdn_manifest.json +36 -0
  7. insight_ui/component_manifest.py +188 -0
  8. insight_ui/config.py +97 -0
  9. insight_ui/configs/__init__.py +334 -0
  10. insight_ui/configs/base.py +194 -0
  11. insight_ui/configs/card.py +314 -0
  12. insight_ui/configs/filter.py +242 -0
  13. insight_ui/configs/forms.py +131 -0
  14. insight_ui/configs/input.py +891 -0
  15. insight_ui/configs/layout.py +441 -0
  16. insight_ui/configs/list.py +156 -0
  17. insight_ui/configs/navigation.py +865 -0
  18. insight_ui/configs/popup.py +94 -0
  19. insight_ui/configs/types.py +624 -0
  20. insight_ui/configs/utils.py +693 -0
  21. insight_ui/icons.py +337 -0
  22. insight_ui/management/__init__.py +3 -0
  23. insight_ui/management/commands/__init__.py +3 -0
  24. insight_ui/management/commands/compile_icons.py +364 -0
  25. insight_ui/management/commands/create_component.py +62 -0
  26. insight_ui/scaffolding.py +458 -0
  27. insight_ui/scaffolding_js.py +102 -0
  28. insight_ui/static/insight_ui/css/prism.css +252 -0
  29. insight_ui/static/insight_ui/css/tailwind.css +3992 -0
  30. insight_ui/static/insight_ui/favicon/android-chrome-192x192.png +0 -0
  31. insight_ui/static/insight_ui/favicon/android-chrome-512x512.png +0 -0
  32. insight_ui/static/insight_ui/favicon/android-chrome-maskable-192x192.png +0 -0
  33. insight_ui/static/insight_ui/favicon/android-chrome-maskable-512x512.png +0 -0
  34. insight_ui/static/insight_ui/favicon/apple-touch-icon.png +0 -0
  35. insight_ui/static/insight_ui/favicon/favicon.ico +0 -0
  36. insight_ui/static/insight_ui/favicon/favicon.svg +26 -0
  37. insight_ui/static/insight_ui/favicon/site.webmanifest +35 -0
  38. insight_ui/static/insight_ui/font/AtkinsonHyperlegibleNext-VariableFont_wght.ttf +0 -0
  39. insight_ui/static/insight_ui/font/OFL.txt +93 -0
  40. insight_ui/static/insight_ui/js/insight-ui-3D-carousel.js +206 -0
  41. insight_ui/static/insight_ui/js/insight-ui-accordion.js +231 -0
  42. insight_ui/static/insight_ui/js/insight-ui-carousel.js +350 -0
  43. insight_ui/static/insight_ui/js/insight-ui-checkbox.js +140 -0
  44. insight_ui/static/insight_ui/js/insight-ui-code-block.js +273 -0
  45. insight_ui/static/insight_ui/js/insight-ui-collapsible.js +93 -0
  46. insight_ui/static/insight_ui/js/insight-ui-debug.js +19 -0
  47. insight_ui/static/insight_ui/js/insight-ui-dropdown.js +231 -0
  48. insight_ui/static/insight_ui/js/insight-ui-flip-card.js +141 -0
  49. insight_ui/static/insight_ui/js/insight-ui-floater.js +515 -0
  50. insight_ui/static/insight_ui/js/insight-ui-init.js +131 -0
  51. insight_ui/static/insight_ui/js/insight-ui-modal.js +188 -0
  52. insight_ui/static/insight_ui/js/insight-ui-multiselect.js +443 -0
  53. insight_ui/static/insight_ui/js/insight-ui-progress-bar.js +766 -0
  54. insight_ui/static/insight_ui/js/insight-ui-range-slider.js +368 -0
  55. insight_ui/static/insight_ui/js/insight-ui-search.js +440 -0
  56. insight_ui/static/insight_ui/js/insight-ui-sidebar.js +368 -0
  57. insight_ui/static/insight_ui/js/insight-ui-state.js +106 -0
  58. insight_ui/static/insight_ui/js/insight-ui-tabs.js +191 -0
  59. insight_ui/static/insight_ui/js/insight-ui-theme-toggle.js +106 -0
  60. insight_ui/static/insight_ui/js/insight-ui-toc-generator.js +252 -0
  61. insight_ui/static/insight_ui/js/insight-ui-utils.js +161 -0
  62. insight_ui/static/insight_ui/js/insight-ui-websocket.js +219 -0
  63. insight_ui/static/insight_ui/svg/insight-ui-logo.svg +19 -0
  64. insight_ui/templates/insight_ui/base.html +130 -0
  65. insight_ui/templates/insight_ui/components/_page_header_content.html +31 -0
  66. insight_ui/templates/insight_ui/components/accordion.html +40 -0
  67. insight_ui/templates/insight_ui/components/alert.html +24 -0
  68. insight_ui/templates/insight_ui/components/article.html +12 -0
  69. insight_ui/templates/insight_ui/components/badge.html +11 -0
  70. insight_ui/templates/insight_ui/components/brand_mark.html +11 -0
  71. insight_ui/templates/insight_ui/components/breadcrumbs.html +39 -0
  72. insight_ui/templates/insight_ui/components/bullet_point_list.html +46 -0
  73. insight_ui/templates/insight_ui/components/button.html +77 -0
  74. insight_ui/templates/insight_ui/components/cards/app_card.html +33 -0
  75. insight_ui/templates/insight_ui/components/cards/card.html +34 -0
  76. insight_ui/templates/insight_ui/components/cards/flip_card.html +83 -0
  77. insight_ui/templates/insight_ui/components/carousel.html +45 -0
  78. insight_ui/templates/insight_ui/components/carousels/3D_carousel.html +61 -0
  79. insight_ui/templates/insight_ui/components/carousels/card_carousel.html +7 -0
  80. insight_ui/templates/insight_ui/components/carousels/image_carousel.html +19 -0
  81. insight_ui/templates/insight_ui/components/charts/_data_table.html +25 -0
  82. insight_ui/templates/insight_ui/components/charts/bar_chart.html +77 -0
  83. insight_ui/templates/insight_ui/components/charts/line_chart.html +69 -0
  84. insight_ui/templates/insight_ui/components/chat.html +24 -0
  85. insight_ui/templates/insight_ui/components/chat_response.html +10 -0
  86. insight_ui/templates/insight_ui/components/checkbox.html +12 -0
  87. insight_ui/templates/insight_ui/components/checkbox_group.html +20 -0
  88. insight_ui/templates/insight_ui/components/corner_ribbon.html +19 -0
  89. insight_ui/templates/insight_ui/components/corner_ribbon_content.html +11 -0
  90. insight_ui/templates/insight_ui/components/dropdown.html +32 -0
  91. insight_ui/templates/insight_ui/components/footer.html +68 -0
  92. insight_ui/templates/insight_ui/components/form.html +57 -0
  93. insight_ui/templates/insight_ui/components/generic_filter.html +24 -0
  94. insight_ui/templates/insight_ui/components/geo_map.html +145 -0
  95. insight_ui/templates/insight_ui/components/hero.html +36 -0
  96. insight_ui/templates/insight_ui/components/htmx_loading_indicator.html +48 -0
  97. insight_ui/templates/insight_ui/components/icons.html +1318 -0
  98. insight_ui/templates/insight_ui/components/infinite_scroll.html +37 -0
  99. insight_ui/templates/insight_ui/components/infinite_scroll_items.html +37 -0
  100. insight_ui/templates/insight_ui/components/infobox.html +8 -0
  101. insight_ui/templates/insight_ui/components/input.html +32 -0
  102. insight_ui/templates/insight_ui/components/layout/collapsible.html +26 -0
  103. insight_ui/templates/insight_ui/components/layout/sidebar.html +81 -0
  104. insight_ui/templates/insight_ui/components/layout/tabs.html +48 -0
  105. insight_ui/templates/insight_ui/components/legal_notice.html +3 -0
  106. insight_ui/templates/insight_ui/components/live_content.html +45 -0
  107. insight_ui/templates/insight_ui/components/live_content_partial.html +17 -0
  108. insight_ui/templates/insight_ui/components/logo.html +25 -0
  109. insight_ui/templates/insight_ui/components/minimal_stepper.html +60 -0
  110. insight_ui/templates/insight_ui/components/modal.html +49 -0
  111. insight_ui/templates/insight_ui/components/multiselect.html +24 -0
  112. insight_ui/templates/insight_ui/components/navbar.html +135 -0
  113. insight_ui/templates/insight_ui/components/page_header.html +31 -0
  114. insight_ui/templates/insight_ui/components/pagination.html +65 -0
  115. insight_ui/templates/insight_ui/components/progress_bar.html +100 -0
  116. insight_ui/templates/insight_ui/components/radio_block.html +80 -0
  117. insight_ui/templates/insight_ui/components/radio_group.html +20 -0
  118. insight_ui/templates/insight_ui/components/range_slider.html +72 -0
  119. insight_ui/templates/insight_ui/components/search_bar.html +64 -0
  120. insight_ui/templates/insight_ui/components/search_bar_result_templates.html +42 -0
  121. insight_ui/templates/insight_ui/components/search_query_builder/sq_builder.html +223 -0
  122. insight_ui/templates/insight_ui/components/search_query_builder/sq_builder_filter.html +53 -0
  123. insight_ui/templates/insight_ui/components/select.html +33 -0
  124. insight_ui/templates/insight_ui/components/sidebar_nav.html +97 -0
  125. insight_ui/templates/insight_ui/components/status_screen.html +52 -0
  126. insight_ui/templates/insight_ui/components/stepper.html +43 -0
  127. insight_ui/templates/insight_ui/components/table.html +47 -0
  128. insight_ui/templates/insight_ui/components/textarea.html +28 -0
  129. insight_ui/templates/insight_ui/components/toc_content.html +7 -0
  130. insight_ui/templates/insight_ui/components/toggle_button.html +40 -0
  131. insight_ui/templates/insight_ui/components/toggle_language.html +32 -0
  132. insight_ui/templates/insight_ui/components/toggle_theme.html +16 -0
  133. insight_ui/templates/insight_ui/components/toggle_view.html +20 -0
  134. insight_ui/templates/insight_ui/components/user_dropdown.html +52 -0
  135. insight_ui/templates/insight_ui/components/websocket.html +41 -0
  136. insight_ui/templates/insight_ui/login.html +116 -0
  137. insight_ui/templates/insight_ui/tailwind_cli.html +1 -0
  138. insight_ui/templatetags/__init__.py +3 -0
  139. insight_ui/templatetags/insight_assets.py +27 -0
  140. insight_ui/templatetags/insight_tags.py +1455 -0
  141. insight_ui/templatetags/layout_tags.py +1305 -0
  142. insight_ui/utils/__init__.py +3 -0
  143. insight_ui/utils/diff.py +27 -0
  144. insight_ui/utils/input.css +1052 -0
  145. insight_ui/utils/pagination.py +58 -0
  146. insight_ui/utils/query_builder_utils.py +93 -0
  147. insight_ui-1.14.0.dist-info/METADATA +882 -0
  148. insight_ui-1.14.0.dist-info/RECORD +151 -0
  149. insight_ui-1.14.0.dist-info/WHEEL +4 -0
  150. insight_ui-1.14.0.dist-info/licenses/LICENSE +661 -0
  151. insight_ui-1.14.0.dist-info/licenses/NOTICE +41 -0
@@ -0,0 +1,48 @@
1
+ # Third-party notices
2
+
3
+ This file ships inside the `insight_ui` package so that the notices below accompany
4
+ every copy of the package (wheel, sdist, container image). The repository-level
5
+ `NOTICE` and `REUSE.toml` carry the same information for the source tree.
6
+
7
+ ## Atkinson Hyperlegible Next
8
+
9
+ `static/insight_ui/font/AtkinsonHyperlegibleNext-VariableFont_wght.ttf`
10
+
11
+ Copyright 2020-2024 The Atkinson Hyperlegible Next Project Authors
12
+ (https://github.com/googlefonts/atkinson-hyperlegible-next).
13
+
14
+ This Font Software is licensed under the SIL Open Font License, Version 1.1.
15
+ The full licence text ships next to the font as `static/insight_ui/font/OFL.txt`.
16
+
17
+ ## Heroicons
18
+
19
+ `icons.py` embeds the outline icons of Heroicons as SVG strings.
20
+
21
+ MIT License
22
+
23
+ Copyright (c) Tailwind Labs, Inc.
24
+
25
+ Permission is hereby granted, free of charge, to any person obtaining a copy
26
+ of this software and associated documentation files (the "Software"), to deal
27
+ in the Software without restriction, including without limitation the rights
28
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
29
+ copies of the Software, and to permit persons to whom the Software is
30
+ furnished to do so, subject to the following conditions:
31
+
32
+ The above copyright notice and this permission notice shall be included in all
33
+ copies or substantial portions of the Software.
34
+
35
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
36
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
37
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
38
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
39
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
40
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
41
+ SOFTWARE.
42
+
43
+ ## Tailwind CSS
44
+
45
+ `static/insight_ui/css/tailwind.css` is generated from the Insight UI design tokens
46
+ with Tailwind CSS and contains Tailwind's preflight and utility styles.
47
+
48
+ MIT License, Copyright (c) Tailwind Labs, Inc. The permission notice above applies.
insight_ui/__init__.py ADDED
@@ -0,0 +1,15 @@
1
+ # SPDX-FileCopyrightText: 2025-2026 Alpin Insight Solutions GmbH & Co. KG
2
+ # SPDX-License-Identifier: AGPL-3.0-only
3
+ """Django Insight UI - Ein auf Barrierefreiheit ausgelegtes UI-Framework für Django."""
4
+
5
+ from __future__ import annotations
6
+
7
+ try: # Prefer generated version file from hatch-vcs at build time
8
+ from ._version import __version__ as __version__ # type: ignore[import-not-found]
9
+ except ImportError: # pragma: no cover - fallback for editable installs
10
+ from importlib.metadata import PackageNotFoundError, version
11
+
12
+ try:
13
+ __version__ = version("insight-ui")
14
+ except PackageNotFoundError:
15
+ __version__ = "0.0.0"
insight_ui/_version.py ADDED
@@ -0,0 +1,24 @@
1
+ # file generated by vcs-versioning
2
+ # don't change, don't track in version control
3
+ from __future__ import annotations
4
+
5
+ __all__ = [
6
+ "__version__",
7
+ "__version_tuple__",
8
+ "version",
9
+ "version_tuple",
10
+ "__commit_id__",
11
+ "commit_id",
12
+ ]
13
+
14
+ version: str
15
+ __version__: str
16
+ __version_tuple__: tuple[int | str, ...]
17
+ version_tuple: tuple[int | str, ...]
18
+ commit_id: str | None
19
+ __commit_id__: str | None
20
+
21
+ __version__ = version = '1.14.0'
22
+ __version_tuple__ = version_tuple = (1, 14, 0)
23
+
24
+ __commit_id__ = commit_id = None
@@ -0,0 +1,113 @@
1
+ # SPDX-FileCopyrightText: 2025-2026 Alpin Insight Solutions GmbH & Co. KG
2
+ # SPDX-License-Identifier: AGPL-3.0-only
3
+ """URL utilities for resolving static asset paths."""
4
+
5
+ import re
6
+ from collections.abc import Mapping
7
+ from typing import Any
8
+
9
+ from django.conf import settings
10
+ from django.templatetags.static import static
11
+
12
+ MINIFIABLE_EXTENSIONS = (".css", ".js")
13
+ SEMVER_PATTERN = re.compile(r"^[0-9]+\.[0-9]+\.[0-9]+$")
14
+
15
+
16
+ def to_minified_asset_path(asset_path: str) -> str:
17
+ """Return the generated minified asset path for CSS and JavaScript files.
18
+
19
+ Args:
20
+ asset_path: The original asset path.
21
+
22
+ Returns:
23
+ The path with '.min' inserted before the extension, or unchanged
24
+ if already minified or not a minifiable extension.
25
+
26
+ """
27
+ for extension in MINIFIABLE_EXTENSIONS:
28
+ min_extension = f".min{extension}"
29
+ if asset_path.endswith(min_extension):
30
+ return asset_path
31
+ if asset_path.endswith(extension):
32
+ return f"{asset_path.removesuffix(extension)}{min_extension}"
33
+
34
+ return asset_path
35
+
36
+
37
+ def _normalise_cdn_version(version: str) -> str:
38
+ """Normalize a version string for CDN URLs.
39
+
40
+ Args:
41
+ version: The version string to normalize.
42
+
43
+ Returns:
44
+ The version prefixed with 'v' if it's a bare semver, otherwise unchanged.
45
+
46
+ """
47
+ if version == "latest" or version.startswith("v") or not SEMVER_PATTERN.match(version):
48
+ return version
49
+ return f"v{version}"
50
+
51
+
52
+ def _cdn_relative_path(asset_path: str) -> str:
53
+ """Convert an asset path to a CDN-relative path.
54
+
55
+ Args:
56
+ asset_path: The full asset path.
57
+
58
+ Returns:
59
+ The path without the 'insight_ui/' prefix and leading slashes.
60
+
61
+ """
62
+ return asset_path.removeprefix("insight_ui/").lstrip("/")
63
+
64
+
65
+ def _asset_config() -> Mapping[str, Any]:
66
+ """Retrieve the asset configuration from Django settings.
67
+
68
+ Returns:
69
+ The 'assets' mapping from INSIGHT_UI settings, or empty dict if not
70
+ configured or invalid.
71
+
72
+ """
73
+ insight_config = getattr(settings, "INSIGHT_UI", {})
74
+ if not isinstance(insight_config, Mapping):
75
+ return {}
76
+
77
+ asset_config = insight_config.get("assets", {})
78
+ if not isinstance(asset_config, Mapping):
79
+ return {}
80
+
81
+ return asset_config
82
+
83
+
84
+ def insight_asset_url(asset_path: str, *, minified: bool | None = None) -> str:
85
+ """Resolve an Insight UI-owned CSS/JS asset to local staticfiles or CDN.
86
+
87
+ Args:
88
+ asset_path: The relative path to the asset.
89
+ minified: Whether to use the minified CDN version. Local staticfiles
90
+ always use the readable package asset.
91
+
92
+ Returns:
93
+ The full URL to the asset (local static URL or CDN URL).
94
+
95
+ """
96
+ asset_config = _asset_config()
97
+ use_cdn = bool(asset_config.get("cdn_enabled", False))
98
+ use_minified = bool(asset_config.get("use_minified", use_cdn))
99
+ if minified is not None:
100
+ use_minified = minified
101
+
102
+ # Generated minified files are CDN-only build artifacts. Local staticfiles
103
+ # deliberately keep serving the readable package sources.
104
+ resolved_path = to_minified_asset_path(asset_path) if use_cdn and use_minified else asset_path
105
+ if not use_cdn:
106
+ return static(resolved_path)
107
+
108
+ base_url = str(asset_config.get("cdn_base_url", "https://cdn.alpininsight.ai")).rstrip("/")
109
+ prefix = str(asset_config.get("cdn_prefix", "insight-ui")).strip("/")
110
+ version = _normalise_cdn_version(str(asset_config.get("cdn_version", "latest")).strip() or "latest")
111
+ relative_path = _cdn_relative_path(resolved_path)
112
+
113
+ return f"{base_url}/{prefix}/{version}/{relative_path}"
insight_ui/brand.py ADDED
@@ -0,0 +1,57 @@
1
+ # SPDX-FileCopyrightText: 2025-2026 Alpin Insight Solutions GmbH & Co. KG
2
+ # SPDX-License-Identifier: AGPL-3.0-only
3
+ """Brand default builders for reusable Insight UI contexts."""
4
+
5
+ from collections.abc import Mapping
6
+ from dataclasses import replace
7
+ from typing import Any, cast
8
+
9
+ from insight_ui.config import get_config
10
+ from insight_ui.configs import FooterDescriptionConfig, LogoConfig, NavbarBrandConfig
11
+
12
+
13
+ def get_brand_defaults() -> Mapping[str, Any]:
14
+ """Return the resolved central brand defaults from ``settings.INSIGHT_UI``."""
15
+ return cast("Mapping[str, Any]", get_config("brand"))
16
+
17
+
18
+ def get_brand_logo_config(*, height: str | None = None) -> LogoConfig | None:
19
+ """Build a logo config from central brand defaults.
20
+
21
+ Args:
22
+ height: Optional height override for a specific context, e.g. login or footer.
23
+
24
+ Returns:
25
+ A ``LogoConfig`` or ``None`` if the brand deliberately disables the logo.
26
+
27
+ """
28
+ brand = get_brand_defaults()
29
+ logo = brand.get("mark").logo
30
+ if not logo:
31
+ return None
32
+
33
+ if height is not None:
34
+ return replace(logo, height=height)
35
+
36
+ return logo
37
+
38
+
39
+ def get_navbar_brand_defaults() -> NavbarBrandConfig:
40
+ """Build the default navbar brand from central brand settings."""
41
+ defaults = get_brand_defaults()
42
+ return NavbarBrandConfig(
43
+ request_url=str(defaults.get("home_url", "")),
44
+ mark=defaults.get("mark"),
45
+ )
46
+
47
+
48
+ def get_footer_description_defaults(*, logo_height: str = "6rem") -> FooterDescriptionConfig:
49
+ """Build the default footer description from central brand settings."""
50
+ brand = get_brand_defaults()
51
+ mark = brand.get("mark")
52
+ title = " ".join(filter(None, [mark.primary_text, mark.secondary_text])) if mark else ""
53
+ return FooterDescriptionConfig(
54
+ title=title,
55
+ text=str(brand.get("footer_text", "")),
56
+ logo=get_brand_logo_config(height=logo_height),
57
+ )
@@ -0,0 +1,36 @@
1
+ {
2
+ "$comment": "Required-verification subset, not the publish list. Release automation determines which package assets are published. The deployer supplies cdn_base_url; full URL = <cdn_base_url>/<cdn_prefix>/<version>/<path>. Documentation: https://insight-ui.com/.",
3
+ "cdn_prefix": "insight-ui",
4
+ "url_template": "{cdn_base_url}/{cdn_prefix}/{version}/{path}",
5
+ "required": [
6
+ {
7
+ "path": "css/tailwind.min.css",
8
+ "loaded_by": "base.html (INSIGHT_UI.stylesheet)",
9
+ "condition": "always",
10
+ "must_contain_selectors": [
11
+ "lg:block",
12
+ "lg:hidden",
13
+ "lg:flex-row",
14
+ "lg:flex-nowrap",
15
+ "lg:w-fit",
16
+ "lg:py-3",
17
+ "lg:bg-transparent",
18
+ "lg:border-none",
19
+ "lg:shadow-none"
20
+ ]
21
+ },
22
+ { "path": "js/insight-ui-init.min.js", "loaded_by": "base.html", "condition": "always" },
23
+ { "path": "js/insight-ui-utils.min.js", "loaded_by": "base.html", "condition": "always" },
24
+ { "path": "js/insight-ui-state.min.js", "loaded_by": "base.html", "condition": "always" },
25
+ { "path": "js/insight-ui-websocket.min.js", "loaded_by": "base.html", "condition": "always" },
26
+ { "path": "js/insight-ui-debug.min.js", "loaded_by": "base.html", "condition": "always" },
27
+ { "path": "js/insight-ui-toc-generator.min.js", "loaded_by": "base.html", "condition": "always" }
28
+ ],
29
+ "conditional": [
30
+ {
31
+ "path": "css/prism.min.css",
32
+ "loaded_by": "base.html",
33
+ "condition": "INSIGHT_UI.load_prism = True"
34
+ }
35
+ ]
36
+ }
@@ -0,0 +1,188 @@
1
+ # SPDX-FileCopyrightText: 2025-2026 Alpin Insight Solutions GmbH & Co. KG
2
+ # SPDX-License-Identifier: AGPL-3.0-only
3
+ """Small component contracts shared by contributor tools and downstream hosts.
4
+
5
+ Examples are data, not executable Python. Config field documentation remains on
6
+ the dataclass; a manifest does not duplicate the parameter reference or a site.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import json
12
+ import re
13
+ from dataclasses import dataclass, is_dataclass
14
+ from importlib import import_module
15
+ from pathlib import Path, PurePosixPath
16
+ from typing import TYPE_CHECKING, Any
17
+
18
+ if TYPE_CHECKING:
19
+ from collections.abc import Mapping
20
+
21
+ CATEGORIES = {
22
+ "layout": "layout",
23
+ "navigation": "navigation",
24
+ "input": "input",
25
+ "popup": "popup",
26
+ "util": "utils",
27
+ "list": "list",
28
+ "filter": "filter",
29
+ "card": "card",
30
+ "form": "forms",
31
+ }
32
+ LEVELS = ("atom", "molecule", "organism")
33
+ SLUG_PATTERN = re.compile(r"[a-z][a-z0-9]*(?:_[a-z0-9]+)*\Z")
34
+
35
+
36
+ @dataclass(frozen=True)
37
+ class ComponentExample:
38
+ """A named, declarative input to the component's public Config."""
39
+
40
+ name: str
41
+ config: dict[str, Any]
42
+
43
+
44
+ @dataclass(frozen=True)
45
+ class ComponentManifest:
46
+ """Versioned metadata, independent of website categories and audit status."""
47
+
48
+ schema_version: int
49
+ slug: str
50
+ name: str
51
+ category: str
52
+ level: str
53
+ config_class: str
54
+ template: str
55
+ uses: tuple[str, ...]
56
+ examples: tuple[ComponentExample, ...]
57
+ js_module: str | None = None
58
+
59
+
60
+ def validate_slug(slug: str) -> str:
61
+ """Accept only component identifiers, never paths or template expressions."""
62
+ if not isinstance(slug, str) or not SLUG_PATTERN.fullmatch(slug):
63
+ message = "Component names must be lowercase snake_case identifiers."
64
+ raise ValueError(message)
65
+ return slug
66
+
67
+
68
+ def manifest_path(slug: str) -> Path:
69
+ """Locate one contract in the imported Insight UI package."""
70
+ return Path(__file__).resolve().parent / "component_manifests" / f"{validate_slug(slug)}.json"
71
+
72
+
73
+ def _package_asset(value: object, prefix: str, suffix: str) -> str:
74
+ """Validate a package-relative template or static asset name."""
75
+ if not isinstance(value, str):
76
+ message = "Component asset names must be strings."
77
+ raise TypeError(message)
78
+ path = PurePosixPath(value)
79
+ if (
80
+ not value.startswith(prefix)
81
+ or not value.endswith(suffix)
82
+ or ".." in path.parts
83
+ or "\\" in value
84
+ or path.as_posix() != value
85
+ ):
86
+ message = f"Invalid package asset: {value!r}"
87
+ raise ValueError(message)
88
+ return value
89
+
90
+
91
+ def _parse_examples(examples: object) -> tuple[ComponentExample, ...]:
92
+ """Keep example validation independent of metadata and Config construction."""
93
+ if not isinstance(examples, list) or not examples:
94
+ message = "At least one declarative example is required."
95
+ raise ValueError(message)
96
+ parsed = []
97
+ for example in examples:
98
+ if not isinstance(example, dict) or set(example) != {"name", "config"}:
99
+ message = "Each example needs exactly name and config."
100
+ raise ValueError(message)
101
+ if not isinstance(example["config"], dict):
102
+ message = "Example config must be a JSON object."
103
+ raise TypeError(message)
104
+ parsed.append(ComponentExample(validate_slug(example["name"]), example["config"]))
105
+ names = [example.name for example in parsed]
106
+ if "default" not in names or len(set(names)) != len(names):
107
+ message = "Examples need unique names and a default example."
108
+ raise ValueError(message)
109
+ return tuple(parsed)
110
+
111
+
112
+ def parse_manifest(data: Mapping[str, Any]) -> ComponentManifest:
113
+ """Validate the stable v1 contract before imports or rendering."""
114
+ required = {
115
+ "schema_version",
116
+ "slug",
117
+ "name",
118
+ "category",
119
+ "level",
120
+ "config_class",
121
+ "template",
122
+ "uses",
123
+ "examples",
124
+ }
125
+ if not isinstance(data, dict) or required - data.keys() or data.keys() - required - {"js_module"}:
126
+ message = "A component manifest has missing or unknown fields."
127
+ raise ValueError(message)
128
+ if type(data["schema_version"]) is not int or data["schema_version"] != 1:
129
+ message = "Only component manifest schema_version 1 is supported."
130
+ raise ValueError(message)
131
+ slug = validate_slug(data["slug"])
132
+ if data["category"] not in CATEGORIES or data["level"] not in LEVELS:
133
+ message = "Unknown component category or atomic level."
134
+ raise ValueError(message)
135
+ if not isinstance(data["name"], str) or not data["name"].strip():
136
+ message = "The component needs a display name."
137
+ raise ValueError(message)
138
+ config_class = data["config_class"]
139
+ if not isinstance(config_class, str) or not re.fullmatch(
140
+ r"insight_ui\.configs\.[a-z][a-z0-9_]*\.[A-Z][A-Za-z0-9]*Config", config_class
141
+ ):
142
+ message = "config_class must reference a public Insight UI Config dataclass."
143
+ raise ValueError(message)
144
+ if not isinstance(data["uses"], list) or not all(isinstance(child, str) for child in data["uses"]):
145
+ message = "uses must be a list of component identifiers."
146
+ raise ValueError(message)
147
+ if len(set(data["uses"])) != len(data["uses"]):
148
+ message = "uses must be a list of unique component identifiers."
149
+ raise ValueError(message)
150
+ uses = tuple(validate_slug(child) for child in data["uses"])
151
+ if slug in uses or (data["level"] == "atom" and uses):
152
+ message = "Components cannot compose themselves; atoms do not compose other components."
153
+ raise ValueError(message)
154
+ parsed_examples = _parse_examples(data["examples"])
155
+ js_module = data.get("js_module")
156
+ return ComponentManifest(
157
+ schema_version=1,
158
+ slug=slug,
159
+ name=data["name"],
160
+ category=data["category"],
161
+ level=data["level"],
162
+ config_class=config_class,
163
+ template=_package_asset(data["template"], "insight_ui/components/", ".html"),
164
+ uses=uses,
165
+ examples=tuple(parsed_examples),
166
+ js_module=_package_asset(js_module, "insight_ui/js/", ".js") if js_module is not None else None,
167
+ )
168
+
169
+
170
+ def load_manifest(path: Path) -> ComponentManifest:
171
+ """Read a JSON contract without evaluating example code."""
172
+ return parse_manifest(json.loads(Path(path).read_text(encoding="utf-8")))
173
+
174
+
175
+ def build_example_config(manifest: ComponentManifest, example_name: str = "default") -> object:
176
+ """Build an example using the package's existing nested-Config coercion."""
177
+ from insight_ui.templatetags.insight_tags import build_config # noqa: PLC0415
178
+
179
+ example = next((entry for entry in manifest.examples if entry.name == example_name), None)
180
+ if example is None:
181
+ message = f"Unknown example {example_name!r} for {manifest.slug}."
182
+ raise ValueError(message)
183
+ module_name, class_name = manifest.config_class.rsplit(".", 1)
184
+ config_type = getattr(import_module(module_name), class_name)
185
+ if not isinstance(config_type, type) or not is_dataclass(config_type):
186
+ message = "The manifest config_class is not a dataclass."
187
+ raise ValueError(message)
188
+ return build_config(config_type, example.config)
insight_ui/config.py ADDED
@@ -0,0 +1,97 @@
1
+ # SPDX-FileCopyrightText: 2025-2026 Alpin Insight Solutions GmbH & Co. KG
2
+ # SPDX-License-Identifier: AGPL-3.0-only
3
+ """Insight UI configuration utilities."""
4
+
5
+ from collections.abc import Mapping
6
+ from typing import Any, cast
7
+
8
+ from django.conf import settings
9
+
10
+ from insight_ui.configs.utils import BrandMarkConfig, LogoConfig
11
+
12
+ CONFIG_DEFAULTS: dict[str, Any] = {
13
+ "webmanifest": "insight_ui/favicon/site.webmanifest",
14
+ "favicon_svg": "insight_ui/favicon/favicon.svg",
15
+ "favicon": "insight_ui/favicon/favicon.ico",
16
+ "apple_touch_icon": "insight_ui/favicon/apple-touch-icon.png",
17
+ "safari_mask_icon": "insight_ui/svg/logo.svg", # Used by Safari pinned tab
18
+ "safari_mask_icon_color": "#5bbad5",
19
+ "msapplication_TileColor": "#da532c", # Sets the background color for a live tile (MS Edge only)
20
+ "theme_color": "#ffffff", # For the search bar on mobile devices
21
+ "meta": {"seo": {"description": "My indispensable app", "keywords": "Django, Insight UI", "author": "It's me"}},
22
+ "stylesheet": "insight_ui/css/tailwind.css", # Only change in case of using alternative stylesheet name
23
+ "navbar_fixed": True, # Should the navigation stick at the top of the window (has impact on the sidebars as well)
24
+ "load_prism": False, # Turn to 'True' to use syntax highlighting
25
+ "load_leaflet": False, # Turn to 'True' to use geo-maps
26
+ "load_echarts": False, # Turn to 'True' to use Chart-Components
27
+ "JS_DEBUG": False, # Turn to 'True' to enable build in browser console logging
28
+ "use_tailwind_cli": False, # Turn to 'True' to enable the tailwind cli, if you want to modify the styles
29
+ "register_url": "", # URL or URL name for registration page (empty = no register button)
30
+ "brand": {
31
+ "home_url": "/",
32
+ "mark": BrandMarkConfig(
33
+ "Django",
34
+ "Insight UI",
35
+ LogoConfig(
36
+ "insight_ui/svg/insight-ui-logo.svg",
37
+ "insight_ui/svg/insight-ui-logo.svg",
38
+ "Insight UI Logo",
39
+ height="2rem",
40
+ ),
41
+ ),
42
+ "footer_text": "A modern, accessible, and responsive UI library for Django projects.",
43
+ },
44
+ "assets": {
45
+ "use_minified": False,
46
+ "cdn_enabled": False,
47
+ "cdn_base_url": "https://cdn.alpininsight.ai",
48
+ "cdn_prefix": "insight-ui",
49
+ "cdn_version": "latest",
50
+ },
51
+ }
52
+
53
+
54
+ def _merge_config(defaults: Mapping[str, Any], user_config: Mapping[str, Any]) -> dict[str, Any]:
55
+ """Deep-merge user configuration into default configuration.
56
+
57
+ Nested mappings are merged recursively; scalar values are overwritten.
58
+
59
+ Args:
60
+ defaults: The default configuration mapping.
61
+ user_config: User-provided configuration to merge in.
62
+
63
+ Returns:
64
+ A new dictionary with user values merged into defaults.
65
+
66
+ """
67
+ merged = dict(defaults)
68
+ for key, value in user_config.items():
69
+ if isinstance(merged.get(key), Mapping) and isinstance(value, Mapping):
70
+ merged[key] = _merge_config(cast("Mapping[str, Any]", merged[key]), value)
71
+ else:
72
+ merged[key] = value
73
+ return merged
74
+
75
+
76
+ def get_config(attribute_name: str = "") -> object:
77
+ """Retrieve Insight UI configuration from Django settings.
78
+
79
+ Merges user-defined settings from ``settings.INSIGHT_UI`` with
80
+ the library defaults in ``CONFIG_DEFAULTS``.
81
+
82
+ Args:
83
+ attribute_name: Optional key to retrieve a specific configuration
84
+ value. If empty, returns the entire configuration dictionary.
85
+
86
+ Returns:
87
+ The value for the requested attribute, or a dictionary containing
88
+ the full merged configuration under the key ``INSIGHT_UI``.
89
+
90
+ """
91
+ user_config = cast("Mapping[str, Any]", getattr(settings, "INSIGHT_UI", {}))
92
+ resolved_config = _merge_config(CONFIG_DEFAULTS, user_config)
93
+
94
+ if attribute_name != "":
95
+ return resolved_config[attribute_name]
96
+
97
+ return {"INSIGHT_UI": resolved_config}